Skip to content

MCP server

Let Claude Code, Cursor, and other MCP clients call Cortrix.

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.
Note

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:

python3 -m venv .venv
source .venv/bin/activate
pip install cortrix-mcp

This gives you the cortrix-mcp command, which is the entry point for the MCP stdio server. Confirm the install:

pip list | grep -E '^(cortrix-mcp|mcp) '
cortrix-mcp               1.0.0rc2
mcp                       2.3.0
Note

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:

VariablePurposeDefault
CORTRIX_URLThe address of cortrix-serverhttp://127.0.0.1:8420
CORTRIX_NAMESPACEThe default namespacedefault
CORTRIX_API_KEYA Bearer token or API key for the target serverEmpty
CORTRIX_MCP_ADMINTurns on admin tools when the server accepts the caller as an adminfalse
CORTRIX_MCP_TIMEOUTHTTP timeout, in seconds30
CORTRIX_AGENT_IDThe 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 defaultcortrix-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:

claude mcp add cortrix --scope project \
  --env CORTRIX_URL=http://127.0.0.1:8420 \
  --env CORTRIX_NAMESPACE=demo \
  -- cortrix-mcp
Added stdio MCP server cortrix with command: cortrix-mcp  to project config

This creates .mcp.json in the current directory:

.mcp.json
{
  "mcpServers": {
    "cortrix": {
      "type": "stdio",
      "command": "cortrix-mcp",
      "args": [],
      "env": {
        "CORTRIX_URL": "http://127.0.0.1:8420",
        "CORTRIX_NAMESPACE": "demo"
      }
    }
  }
}

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.

Tip

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

~/.cursor/mcp.json
{
  "mcpServers": {
    "cortrix": {
      "command": "cortrix-mcp",
      "env": {
        "CORTRIX_URL": "http://127.0.0.1:8420",
        "CORTRIX_NAMESPACE": "demo"
      }
    }
  }
}

Cline

Add this to cline_mcp_settings.json in your VS Code user directory:

cline_mcp_settings.json
{
  "mcpServers": {
    "cortrix": {
      "command": "cortrix-mcp",
      "env": {
        "CORTRIX_URL": "http://127.0.0.1:8420",
        "CORTRIX_NAMESPACE": "demo"
      },
      "disabled": false
    }
  }
}

Verify

Once connected, ask the agent to call cortrix_health. The result’s meta.category should be success:

{
  "data": { "status": "alive", "uptime_seconds": 195, "version": "1.0.0-rc.2" },
  "meta": {
    "retryable": false,
    "category": "success",
    "retry_after_ms": null,
    "structured_data": {
      "trace_id": "17912bb9-4f29-4a2f-9a35-e5ccd2ac28c8",
      "session_id": "mcp-session-da64d7e40fe9"
    }
  }
}

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:

## Cortrix

The documents in <which files, for example "docs/ and design/"> are indexed in
Cortrix, namespace `<your-namespace>`. Search them through the `cortrix` MCP server.

- Before you open those files to answer a question, search with `cortrix_query`
  and pass `namespaces: ["<your-namespace>"]`. Start with the question itself, or
  the names and terms you need.
- Open a file only for what the hits leave open, and go to the files the hits point to.
- Cite from each hit's `metadata`: `doc_id`, `source_path`, and the fields this
  project sets at upload.

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:

claude --disallowedTools "Read Grep Glob"

Keep them on in a session that also edits code: Claude Code reads a file before it edits it.

Tools

GroupTools
Corecortrix_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
Extendedcortrix_cross_ns_query, cortrix_async_upload, cortrix_memory_search_filter, cortrix_memory_extract_trigger
Tasks and explaincortrix_memory_extract, cortrix_task_status, cortrix_cancel_task, cortrix_query_explain
Memory and operationscortrix_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
Admincortrix_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 codeRetryableCategorySuggested wait (ms)
CX_ERR_MCP_BACKEND_TIMEOUTYestransient1000
CX_ERR_MCP_BACKEND_UNAVAILABLEYestransient5000
CX_ERR_MCP_SCHEMA_VALIDATION_FAILNopermanent—
CX_ERR_MCP_TOOL_NOT_FOUNDNopermanent—
CX_ERR_MCP_AUTH_MISSINGNoauth—
CX_ERR_MCP_ADMIN_REQUIREDNoauth—

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:

curl -fsS http://127.0.0.1:8420/api/v1/traces/<session_id>

Protocol compatibility

  • The modern protocol 2026-07-28, through server/discover.
  • The legacy protocol 2025-11-25, through the initialize handshake.
  • Python dependency: mcp>=2.0.0,<3.0.0.

Next steps