Provides AI agents with persistent memory, hybrid search, and goal graphs through a knowledge-management API.
Also known as contextq/contextq-mcp, @contextq/mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 668
- Latest version
- 2.1.1
- Last commit
- Oct 1, 2026
- License
- MIT
What is ContextQ MCP?
ContextQ provides AI agents with persistent memory, hybrid search, and goal graphs through a knowledge-management API.
Summary generated from the project's README
About ContextQ MCP server
Giving AI agents persistent memory and goal-oriented reasoning is what contextq-mcp enables for developers using tools like Claude Desktop, Claude Code, Cursor, or Windsurf. By connecting to a ContextQ knowledge-management API, this server provides agents with access to hybrid search, agent sessions, and goal graphs. It acts as a stateless proxy that forwards tool calls to your specific ContextQ server using a required API key and base URL.
To manage token costs, the server connects with a curated set of approximately 24 tools by default. Users can access the full suite of 89 tools by setting the CONTEXT_MCP_TOOL_PROFILE environment variable to full or by using specific tools like ctx_tool_groups to load additional capabilities on demand. This setup allows for sophisticated memory management through tools such as ctx_save, ctx_search, and ctx_ingest, while maintaining tenant isolation through scoped API keys.
What you can do with it
- 1Ingesting new knowledge sourcesA developer can instruct an agent to fetch and parse new data to expand its knowledge base.
- 2Organizing workspace context via clusteringYou can use the server to cluster various contexts using vector similarity for better organization.
- 3Managing large tool sets efficientlyDevelopers can keep tool lists small to save tokens while still accessing all available functions.
Written from the project's README. Every use case is checked against a quote from it.
How to install ContextQ MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ContextQ MCP in Claude Code
$ claude mcp add --env 'CONTEXT_API_KEY=<YOUR_CONTEXT_API_KEY>' --env 'CONTEXT_API_URL=<CONTEXT_API_URL>' contextq-mcp -- npx -y @contextq/mcpInstall ContextQ MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"contextq-mcp": {
"command": "npx",
"args": [
"-y",
"@contextq/mcp"
],
"env": {
"CONTEXT_API_KEY": "<YOUR_CONTEXT_API_KEY>",
"CONTEXT_API_URL": "<CONTEXT_API_URL>"
}
}
}
}Install ContextQ MCP in VS Code
.vscode/mcp.json
{
"servers": {
"contextq-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@contextq/mcp"
],
"env": {
"CONTEXT_API_KEY": "<YOUR_CONTEXT_API_KEY>",
"CONTEXT_API_URL": "<CONTEXT_API_URL>"
}
}
}
}Install ContextQ MCP in VS Code CLI
$ code --add-mcp '{"name":"contextq-mcp","type":"stdio","command":"npx","args":["-y","@contextq/mcp"],"env":{"CONTEXT_API_KEY":"<YOUR_CONTEXT_API_KEY>","CONTEXT_API_URL":"<CONTEXT_API_URL>"}}'Install ContextQ MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"contextq-mcp": {
"command": "npx",
"args": [
"-y",
"@contextq/mcp"
],
"env": {
"CONTEXT_API_KEY": "<YOUR_CONTEXT_API_KEY>",
"CONTEXT_API_URL": "<CONTEXT_API_URL>"
}
}
}
}Install ContextQ MCP in Codex
$ codex mcp add contextq-mcp --env 'CONTEXT_API_KEY=<YOUR_CONTEXT_API_KEY>' --env 'CONTEXT_API_URL=<CONTEXT_API_URL>' -- npx -y @contextq/mcpInstall ContextQ MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.contextq-mcp] command = "npx" args = ["-y", "@contextq/mcp"] [mcp_servers.contextq-mcp.env] CONTEXT_API_KEY = "<YOUR_CONTEXT_API_KEY>" CONTEXT_API_URL = "<CONTEXT_API_URL>"
Install ContextQ MCP in Gemini CLI
$ gemini mcp add -s user -e 'CONTEXT_API_KEY=<YOUR_CONTEXT_API_KEY>' -e 'CONTEXT_API_URL=<CONTEXT_API_URL>' contextq-mcp npx -- -y @contextq/mcpInstall ContextQ MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"contextq-mcp": {
"command": "npx",
"args": [
"-y",
"@contextq/mcp"
],
"env": {
"CONTEXT_API_KEY": "<YOUR_CONTEXT_API_KEY>",
"CONTEXT_API_URL": "<CONTEXT_API_URL>"
}
}
}
}Configuration
CONTEXT_API_KEYRequiredSecretContextQ API key (sk_live_...), created in the ContextQ dashboard
CONTEXT_API_URLRequiredContextQ API base URL, https://app.contextq.dev for the hosted service
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT
| Name | Description | |
|---|---|---|
| CONTEXT_API_KEY | ContextQ API key (sk_live_...), created in the ContextQ dashboard | RequiredSecret |
| CONTEXT_API_URL | ContextQ API base URL, https://app.contextq.dev for the hosted service | Required |
| CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablecontextq/contextq-mcp is public and reachablegithub.com/contextq/contextq-mcp ↗Pass
- Package names this repository as its source@contextq/mcp names contextq/contextq-mcp as sourcenpmjs.com/package/@contextq/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-01github.com/contextq/contextq-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @contextq/mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHub@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:
| 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_URLand 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_KEYis sent as anAuthorization: Bearerheader 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.
License
MIT
ContextQ MCP questions
How do I add ContextQ MCP to Claude Code?
Run claude mcp add --env 'CONTEXT_API_KEY=<YOUR_CONTEXT_API_KEY>' --env 'CONTEXT_API_URL=<CONTEXT_API_URL>' contextq-mcp -- npx -y @contextq/mcp in your terminal. Add --scope user to make it available in every project.
How do I add ContextQ MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What is the difference between the default and full tool profiles?
The default profile loads a curated set of approximately 24 tools to keep token costs low, while the full profile loads all 89 tools from the start.
Why am I seeing timeout errors with certain tools?
Some tools perform heavy operations like LLM synthesis or kNN scans that take longer than standard MCP timeouts; you should increase the per-server request timeout.
Is my data secure when using this server?
The server acts as a stateless proxy that only forwards agent requests, and all API keys are tenant-scoped to prevent cross-tenant data leaks.