MCP server
On this page you’ll install cortrix-mcp and connect it to an MCP client, so the agent in that client can query, upload documents, and manage memory.
cortrix-mcp exposes Cortrix’s HTTP API as 31 MCP tools: 29 regular tools and 2 admin tools. It talks HTTP directly to a running cortrix-server.
Prerequisites
- A running Cortrix service. See the Quickstart.
- Python 3.10 or later.
- An MCP client that supports stdio transport.
Only local stdio transport is supported. Cortrix doesn’t expose a remote or loopback Streamable HTTP MCP endpoint.
Install
Install the package from PyPI into a virtual environment:
This gives you the cortrix-mcp command, which is the entry point for the MCP stdio server. Confirm the install:
Cortrix is in pre-release, so pip installs the latest pre-release, 1.0.0rc2. The Docker image cortrix/mcp isn’t published to a registry yet. To run the server in a container, build the image from cortrix-mcp/ in a clone of the repository.
Configuration
All configuration is passed through environment variables:
| Variable | Purpose | Default |
|---|---|---|
CORTRIX_URL | The address of cortrix-server | http://127.0.0.1:8420 |
CORTRIX_NAMESPACE | The default namespace | default |
CORTRIX_API_KEY | A Bearer token or API key for the target server | Empty |
CORTRIX_MCP_ADMIN | Turns on admin tools when the server accepts the caller as an admin | false |
CORTRIX_MCP_TIMEOUT | HTTP timeout, in seconds | 30 |
CORTRIX_AGENT_ID | The agent identity sent as X-Agent-Id on every request. Allowed characters are [A-Za-z0-9_.:/-], up to 128 characters. An invalid value falls back to the default | cortrix-mcp |
The quickstart service has no authentication, so you don’t need CORTRIX_API_KEY. Its demo data lives in the demo namespace, so the examples below set the default namespace to demo.
Connect a client
Claude Code
Run this in your project directory. cortrix-mcp needs to be on your PATH. Otherwise, give the absolute path inside your virtual environment:
This creates .mcp.json in the current directory:
Claude Code asks you to approve a project-scoped MCP server before using it. Start claude, approve cortrix, and then run /mcp to check the connection.
.mcp.json can contain absolute paths from your machine. The Cortrix repository’s .gitignore already ignores this file. Whether to commit it in your own project is up to you.
Cursor
Add this to ~/.cursor/mcp.json:
Cline
Add this to cline_mcp_settings.json in your VS Code user directory:
Verify
Once connected, ask the agent to call cortrix_health. The result’s meta.category should be success:
Then ask it to use cortrix_query to look up “What does semantic storage keep close to the agents that need it?”. It should return content from quickstart-demo.txt.
Tell the agent how to use Cortrix
Connecting the server gives the agent the tools. It doesn’t tell the agent which of your files are indexed, or that it should search them before it opens them. Add a short section like this to your project’s agent instructions, such as CLAUDE.md for Claude Code or AGENTS.md, and fill in the placeholders:
For the quickstart’s demo data, the namespace is demo.
When to turn off the agent’s own file tools
An agent that also has its own tools for reading and searching files, such as Claude Code’s Read, Grep and Glob, may search Cortrix and then keep opening files on its own. Each extra turn sends the whole conversation again, so a long answer can cost several times more. For a session that only answers questions from the indexed documents, start Claude Code without those tools:
Keep them on in a session that also edits code: Claude Code reads a file before it edits it.
Tools
| Group | Tools |
|---|---|
| Core | cortrix_health, cortrix_query, cortrix_upload, cortrix_list_documents, cortrix_list_namespaces, cortrix_create_namespace, cortrix_memory_search, cortrix_log_interaction, cortrix_list_interactions, cortrix_document_status, cortrix_add_watcher, cortrix_list_watchers |
| Extended | cortrix_cross_ns_query, cortrix_async_upload, cortrix_memory_search_filter, cortrix_memory_extract_trigger |
| Tasks and explain | cortrix_memory_extract, cortrix_task_status, cortrix_cancel_task, cortrix_query_explain |
| Memory and operations | cortrix_memory_get_audit, cortrix_memory_revoke_fact, cortrix_memory_opt_out, cortrix_batch_submit, cortrix_list_operations, cortrix_memory_list, cortrix_memory_create, cortrix_memory_edit, cortrix_memory_invalidate |
| Admin | cortrix_admin_db_credential_register, cortrix_admin_db_import_run |
For each tool’s parameters and status, see MCP tools.
Response schema
Every tool returns two layers: data holds the result, and meta tells the agent whether the call can be retried.
When a tool, the backend, authentication, a timeout, or validation fails, the result comes back with isError=true and keeps code, retryable, category, retry_after_ms, and structured_data.
The adapter defines 6 stable error codes of its own:
| Error code | Retryable | Category | Suggested wait (ms) |
|---|---|---|---|
CX_ERR_MCP_BACKEND_TIMEOUT | Yes | transient | 1000 |
CX_ERR_MCP_BACKEND_UNAVAILABLE | Yes | transient | 5000 |
CX_ERR_MCP_SCHEMA_VALIDATION_FAIL | No | permanent | — |
CX_ERR_MCP_TOOL_NOT_FOUND | No | permanent | — |
CX_ERR_MCP_AUTH_MISSING | No | auth | — |
CX_ERR_MCP_ADMIN_REQUIRED | No | auth | — |
Errors that come from cortrix-server itself pass through unchanged.
Trace a call
Every backend request carries X-Session-Id, a fresh X-Trace-Id, and X-Agent-Id. The server adopts these identifiers, so you can use the session_id in a tool’s meta.structured_data to look up the server-side trace directly:
Protocol compatibility
- The modern protocol
2026-07-28, throughserver/discover. - The legacy protocol
2025-11-25, through the initialize handshake. - Python dependency:
mcp>=2.0.0,<3.0.0.