MCP server for ContextQ -- exposes the ContextQ knowledge-management API (89 tools: save, search, ingest, goal graphs, agent sessions, relays, and more) as Model Context Protocol tools. A curated ~24-tool default set loads at connection to keep the token cost of tools/list low; the rest load on demand or via CONTEXT_MCP_TOOL_PROFILE=full -- see below.

npx -y @contextq/mcp

Client configuration

Two environment variables are required in every client:

Variable	Description
`CONTEXT_API_URL`	Base URL of your ContextQ server (e.g. `https://ctx.example.com`)
`CONTEXT_API_KEY`	API key sent as `Authorization: Bearer` on every request

Optional:

Variable	Description
`CONTEXT_MCP_TOOL_PROFILE`	`default` (default if unset) loads a curated ~24-tool set at connection, well under most hosts' comfortable tool-list budget; `full` loads all ~89 tools from the start. On `default`, the rest stay reachable via the `ctx_tool_groups` (list) / `ctx_load_tool_group` (load) tools without reconnecting -- see `docs/mcp-tools.md` "Discoverability under ToolSearch deferral"

Setup paths: Claude Code and Claude Desktop have automated setup via the contextq init CLI command. Cursor, Windsurf, and Cline require manual config file editing — see docs/mcp-setup.md for the full reference.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

Claude Code

claude mcp add contextq \
  -e CONTEXT_API_KEY=sk_live_YOUR_API_KEY \
  -e CONTEXT_API_URL=https://ctx.example.com \
  -- npx -y @contextq/mcp

Cursor

Add to your Cursor MCP config (.cursor/mcp.json or Settings > MCP):

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

Windsurf

STATUS (2026-06-02): Windsurf was rebranded as Devin Desktop and Cascade was end-of-lifed (2026-07-01). If you have an existing Windsurf install, the configuration below still applies, but new installations should use Devin Desktop instead. Devin Desktop uses the same MCP config format under .devin/mcp.json.

Add to your Windsurf MCP config (.windsurf/mcp.json):

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

What data is sent and tenant isolation

Only the requests your agent makes are sent. The MCP server is a stateless proxy -- it forwards each tool call to the ContextQ API via CONTEXT_API_URL and returns the response. No telemetry, no background sync, no usage tracking beyond what your ContextQ server logs.
Tenant-scoped API keys. Every ContextQ API key is bound to a single tenant. All /api/* endpoints enforce tenant isolation -- an API key can only access the tenant it was issued for. Cross-tenant data leaks are impossible at the API layer.
Per-request auth. Your CONTEXT_API_KEY is sent as an Authorization: Bearer header on every call. It never appears in tool names, argument schemas, or responses returned to the LLM.

Client timeout configuration

A handful of ContextQ tools run LLM calls, kNN scans, or bulk DB operations server-side and can legitimately take longer than a typical MCP client's default request timeout. If your client aborts before the server responds, you will see a timeout error that looks like a broken tool — it usually isn't. Configure a longer per-server timeout for this MCP server rather than assuming the tool is hung.

Slow-class tools (recommend a longer timeout, e.g. 120000-180000 ms depending on workspace size):

Tool	Why it's slow
`ctx_dream`	Clusters a workspace's contexts via vector similarity, then runs one LLM synthesis call per cluster.
`ctx_evolve`	Runs LLM judging over up to 20 nearest-neighbor contexts to decide links/archival.
`ctx_ingest`	Fetches/parses a source and runs LLM claim extraction + kNN diffing. Large or URL-sourced ingests already return `{ jobId, statusUrl }` and expect polling via `ctx_ingest_status` — but small inline ingests still run synchronously and can take several seconds.
`ctx_regenerate_mocs`	Re-clusters all of a tenant's contexts and runs one LLM synthesis call per cluster (admin scope).
`ctx_memory_review_run`	Samples older contexts and asks the LLM to verdict each one (superadmin scope).
`ctx_bulk_update`	Applies a lifecycle/archive patch to up to 200 context ids in one call — bounded, but still slower than a single-row update.
`ctx_audit_cleanup_run`	Deletes up to 5000 `activity_logs` rows in one pass (superadmin scope).
`ctx_snapshot_create` / `ctx_fork_world` / `ctx_diff_world`	Clone or diff a workspace's full memory state (contexts, links, goal graph) — cost scales with workspace size.

Everything else (ctx_search, ctx_get, ctx_save, ctx_list, agent_*, goal_*, relay_*, etc.) is ordinary CRUD/search and should complete well within a default client timeout.

These numbers are starting points, not guarantees — actual latency depends on your ContextQ server's hardware, workspace size, and configured LLM/embedding provider. Measure against your own deployment before tuning tighter.

`.mcp.json` per-server `request_timeout_ms`

Most MCP clients that support .mcp.json (including Claude Code) accept a per-server request_timeout_ms to override the client's default request timeout for every tool call on that server:

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      },
      "request_timeout_ms": 120000
    }
  }
}

request_timeout_ms applies per server, not per tool — if you regularly call slow-class tools, size it for the slowest one you expect to hit, not the average. Claude Code 2.1.206 fixed a bug where this field was silently ignored (a 60s default was applied regardless); confirm your Claude Code version is at least 2.1.206 if the setting doesn't seem to take effect.

Claude Code idle timeout

Independently of request_timeout_ms, Claude Code (2.1.187+) also enforces CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT — an idle-abort timeout (default around 5 minutes) that fires if an MCP tool call produces no activity for that long. Set it in your shell environment (not .mcp.json) when calling slow-class tools against a large workspace:

export CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=300000   # milliseconds; raise if ctx_dream/ctx_ingest still time out

Treat both settings as recommendations, not guarantees, of how long any given call will take.

API version compatibility

The 99-tool surface exposed by this MCP server is a direct projection of the ContextQ API (24 loaded by default, the rest via CONTEXT_MCP_TOOL_PROFILE=full or on-demand -- see "Client configuration" above). The tool count and signatures drift with the server. Pin compatible versions:

MCP package	ContextQ server API
`@contextq/mcp@2.x`	ContextQ v2.x (99 tools)

When upgrading your ContextQ server, check the changelog and bump the MCP package to the matching major version. A version mismatch may surface unknown tools or break call signatures.