Contextq MCP README

@contextq/mcp

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:

Optional:

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):

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:

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.

License

MIT