Contextq MCP

What contextq-mcp MCP server does

The contextq-mcp MCP server connects an MCP-compatible client to a ContextQ knowledge-management deployment. It exposes ContextQ operations for persistent memory, search, ingestion, goal graphs, agent sessions, relays, and related API functions as callable MCP tools.

This places the project in the 🧠 Knowledge & Memory category. It is intended for agents that need to save and retrieve information across interactions, inspect or update structured goals, ingest external material, or coordinate through ContextQ's session and relay features.

The package runs as a stateless proxy. It does not maintain a separate local memory store or perform background synchronization. Requests made by the agent are sent to the configured ContextQ API, and the API response is returned to the client.

How it works

The contextq-mcp MCP server starts with the npm command npx -y @contextq/mcp and communicates with the MCP client over stdio. Each tool call is forwarded to the ContextQ server identified by CONTEXT_API_URL. CONTEXT_API_KEY is sent on every request as a Bearer token.

By default, the connection exposes a curated set of roughly 24 tools to keep the initial tools/list response smaller. Other tools can be discovered and loaded through the tool-group functions without reconnecting. Setting CONTEXT_MCP_TOOL_PROFILE=full makes the complete API surface available at startup. The available tool count and signatures follow the ContextQ API version, so the MCP package and ContextQ server should use matching major versions.

ContextQ API keys are tenant-scoped, and the API enforces tenant isolation. The MCP proxy itself reports no telemetry or background usage activity beyond requests recorded by the ContextQ deployment.

Setup and configuration

Every client configuration requires these environment variables:

• CONTEXT_API_URL: Base URL of the ContextQ server.
• CONTEXT_API_KEY: API key used for authenticated requests.

Claude Desktop and Claude Code have setup paths through the contextq init command. Cursor, Windsurf, and Cline require adding the MCP server manually to their configuration. The standard command uses npx with the @contextq/mcp package and passes the two required variables in the server environment.

Some operations perform server-side LLM calls, vector scans, ingestion, bulk updates, or workspace cloning. Configure a longer MCP request timeout when using these operations. Claude Code also has a separate idle timeout setting for calls that produce no activity for an extended period.

Tools and capabilities

The contextq-mcp MCP server provides tools covering:

• Context saving, retrieval, listing, updating, and search.
• Source ingestion with status polling for longer jobs.
• Goal graph operations and agent session management.
• Relay operations for communication through ContextQ.
• Tool-group discovery and on-demand tool loading.
• Workspace snapshots, forks, diffs, memory review, and lifecycle operations where supported by the connected API.

The default profile is useful when tool-list size matters. The full profile is suited to clients or workflows that need the entire exposed API immediately.

Limitations and notes

Response time depends on the ContextQ deployment, workspace size, and configured embedding or LLM provider. Tools such as dreaming, evolution, ingestion, regeneration, memory review, bulk updates, audit cleanup, and workspace snapshot operations may need substantially longer timeouts than ordinary CRUD or search calls.

The MCP package is a direct projection of the ContextQ API, so upgrades can change tool names, arguments, or availability. Check the ContextQ changelog and keep package and server major versions aligned. The package is licensed under MIT.