Skip to main content

MCP

The MCP server (@vagarylabs/mcp-server) is a thin wrapper over the Vagaris REST API for agents that speak the Model Context Protocol — Claude Code, Codex, and any other MCP client. It does not touch the database and reimplements no business logic.

Install and run​

npm install -g @vagarylabs/mcp-server
vagaris-mcp-server

The command is vagaris-mcp-server. vagris-mcp-server and paperclip-mcp-server are kept as aliases that run the same server, because MCP client configurations name the command to spawn and live outside this repository; run from a terminal, an alias prints a one-line deprecation notice to stderr. The transport is stdio: the client launches the process and talks over its stdin/stdout.

Configuration​

Everything comes from the environment, read under the canonical VAGARIS_* prefix, with VAGARIS_* and then PAPERCLIP_* as accepted fallbacks:

SuffixRequiredMeaning
API_URLyesVagaris base URL, for example http://localhost:3100 (/api is appended if missing)
API_KEYyesBearer token — an agent API key from vagaris agent local-cli
COMPANY_IDnoDefault company for company-scoped tools
AGENT_IDnoDefault agent for checkout helpers
RUN_IDnoRun id forwarded on mutating requests, for attribution
MCP_TOOL_MODEnofull (default), propose, or allowlist
MCP_TOOL_ALLOWLISTnoComma-separated tool names exposed when mode is allowlist

propose curates the tool set to reads plus comment, suggest-tasks, ask-user-questions and request-confirmation — the safe surface for a propose-only seat. allowlist exposes only the named tools, which is how a lease's explicit tool policy reaches an MCP-connected agent.

The quickest way to get the required values is the export block printed by:

vagaris agent local-cli <agent> --company-id <company-id>

Client configuration​

Most MCP clients accept a JSON block of this shape:

{
  "mcpServers": {
    "vagaris": {
      "command": "vagaris-mcp-server",
      "env": {
        "VAGARIS_API_URL": "http://localhost:3100",
        "VAGARIS_API_KEY": "<agent-api-key>",
        "VAGARIS_COMPANY_ID": "<company-id>",
        "VAGARIS_AGENT_ID": "<agent-id>"
      }
    }
  }
}

Tools​

Read tools: paperclipMe, paperclipInboxLite, paperclipListAgents, paperclipGetAgent, paperclipListIssues, paperclipGetIssue, paperclipGetHeartbeatContext, paperclipListComments, paperclipGetComment, paperclipListIssueApprovals, paperclipListDocuments, paperclipGetDocument, paperclipListDocumentRevisions, paperclipListProjects, paperclipGetProject, paperclipGetIssueWorkspaceRuntime, paperclipWaitForIssueWorkspaceService, paperclipListGoals, paperclipGetGoal, paperclipListApprovals, paperclipGetApproval, paperclipGetApprovalIssues, paperclipListApprovalComments.

Write tools: paperclipCreateIssue, paperclipUpdateIssue, paperclipCheckoutIssue, paperclipReleaseIssue, paperclipAddComment, paperclipSuggestTasks, paperclipAskUserQuestions, paperclipRequestConfirmation, paperclipUpsertIssueDocument, paperclipRestoreIssueDocumentRevision, paperclipControlIssueWorkspaceServices, paperclipCreateApproval, paperclipLinkIssueApproval, paperclipUnlinkIssueApproval, paperclipApprovalDecision, paperclipAddApprovalComment.

Escape hatch: paperclipApiRequest for any other REST endpoint.

Tool names keep the paperclip prefix for compatibility with existing client configurations and prompts.

Relationship to the CLI​

The MCP server and the CLI are two clients of the same API with the same credential model. Use the CLI from a terminal or a script; use the MCP server from inside an agent. A run hosted by vagaris dev can carry the tool policy into the MCP server through MCP_TOOL_MODE=allowlist and MCP_TOOL_ALLOWLIST.