Skip to main content
The Copass CLI ships a Model Context Protocol server over stdio. It exposes the core Copass surface as tools any MCP-compatible agent can call — Claude Code, Cursor, and any future client that speaks MCP.

​
Start the server

copass mcp
That’s it. The server runs in the foreground, listens for JSON-RPC on stdio, and exits when the client disconnects. Every tool invocation re-authenticates from ~/.olane/config.json and targets the same Copass account your CLI is logged into.

​
Tools exposed

ToolCLI equivalentPurpose
check_project_statuscopass status --jsonReport refs, watch state, and encryption key source for the caller’s cwd
entitiescopass entities <q> --jsonLook up canonical entities by vector similarity — lightweight disambiguation
discovercopass discover <msg> --jsonRanked menu of related context paths — the first step of the progressive disclosure pattern
interpretcopass interpret <items-json> --json1-2 paragraph brief pinned to one or more tuples of canonical IDs picked from discover
searchcopass search <q> --jsonDeep semantic search — synthesized natural-language answer
questioncopass question <q> --jsonNatural-language question against the knowledge graph
ingestcopass ingest … --jsonPush content through the sandbox data source (file or inline)
index_projectcopass index --mode … --jsonFull / incremental indexing
Each tool is a thin wrapper that shells out to the matching copass <cmd> --json invocation. The MCP tool schema and the CLI flag surface stay in lock-step — no API contract drift between the two.
discover → interpret → search form a progressive-disclosure gradient: cheap menu, pinned brief, full answer. Agents pay for depth only where they commit. Window-aware by default — content the agent has already seen doesn’t get re-delivered on follow-up turns.

​
Claude Code integration

Add Copass to your Claude Code MCP config so it can ingest and query without leaving the editor: 
{
  "mcpServers": {
    "copass": {
      "command": "copass",
      "args": ["mcp"]
    }
  }
}
Reload Claude Code. You’ll see the Copass tools become available in the tool list.

​
Cursor / generic MCP clients

Any client that supports stdio MCP transport can register copass mcp as a server. The config shape is usually: 
{
  "command": "copass",
  "args": ["mcp"],
  "env": {}
}
No environment variables are required — the server reads auth state from ~/.olane/config.json on each invocation.

​
How it works under the hood

MCP client (Claude Code, Cursor, …)
   ↓  stdio JSON-RPC
copass mcp
   ↓  per-tool handler spawns:
copass <cmd> [flags] --json
   ↓  stdout captured, parsed
JSON returned as the MCP tool result
The indirection means:
  • No state duplication between the MCP server and the CLI — they are the same binary.
  • Same auth, same config, same .olane/refs.json — a cwd that works from the terminal works over MCP.
  • JSON contract stability matters — every CLI command’s --json output is, in effect, a public API.

​
Which directory does the server use?

The MCP server resolves sandbox + project context from the working directory the client started it in. If your MCP client spawns copass mcp from your project root, every tool call is scoped to that project’s .olane/refs.json. If you need cross-project access, spawn one server per project (most MCP clients support multiple entries).

​
Next steps

  • Claude Code Extension — opinionated install of the three retrieval tools into Claude Code, with the window-aware prompt-submit hook.
  • Progressive Disclosure — first-principles argument for why discover / interpret / search is three calls instead of one.
  • CLI — the full command surface the MCP tools wrap.
  • SDK — @copass/mcp (standalone MCP server) plus framework adapters for Vercel AI SDK / LangChain / Mastra / Pydantic AI.
  • API Reference — the raw endpoints behind every tool.