This is the multi-page printable view of this section. .
Integrations
- 1: Choose an access path
- 2: MCP server
- 3: Python SDK
- 4: Framework adapters
- 5: Built-in Agent
- 6: pgcortrix
Cortrix offers several access paths: the HTTP API, MCP, the Python SDK, framework adapters, and a built-in Agent.
1 - Choose an access path
Cortrix has four access paths. This page helps you pick the one that fits your situation.
How to choose
| Your situation | Choose |
|---|---|
| You need precise control over requests, retries, authentication, and deployment, or you’re not using Python | HTTP API |
| You want an agent in your IDE, or another MCP-compatible client, to call Cortrix | MCP server |
| You’re writing a Python application, a RAG pipeline, or a test script | Python SDK |
| You want local fixed-flow chat over what’s in Cortrix, without wiring up an agent framework | Built-in Agent |
HTTP API
Every other access path ends up calling the HTTP API. The contract is api/openapi.yaml in the repository. See the HTTP API reference for every endpoint.
Check that the service is ready:
Run a query:
When authentication is on, send your API key in the X-API-Key header.
MCP server
The MCP server exposes Cortrix’s HTTP API as a set of MCP tools covering health, query, upload, namespace management, memory, task status, directory watchers, and admin database import.
It supports local stdio transport only. There is no remote Streamable HTTP endpoint.
For setup, see MCP server.
Python SDK
The Python SDK provides a synchronous client, Cortrix, and an asynchronous client, AsyncCortrix. Both are fully typed and map the server’s structured errors to exceptions with fields.
It exposes resources for documents, namespaces, query, memory, directory watchers, authentication, tenants, system information, operations, and database import. For the status of each resource, see Python SDK.
For installation and usage, see Python SDK.
Built-in Agent
The built-in Agent is a FastAPI service that provides fixed-flow chat over Cortrix storage. It needs the agent_llm role configured, and it’s off by default in the quickstart.
Chat is the only mode.
See Built-in Agent.
Next steps
2 - 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.
Next steps
3 - Python SDK
On this page you’ll install the Cortrix Python SDK, connect to a local Cortrix service, and run a query.
The SDK provides a synchronous client, Cortrix, and an asynchronous client, AsyncCortrix, both fully typed. Its runtime dependency is httpx, plus typing-extensions on Python versions before 3.12.
Prerequisites
- A running Cortrix service. See the Quickstart.
- Python 3.9 or later.
Install
Install the package from PyPI into a virtual environment:
Confirm the installed version:
Cortrix is in pre-release, so pip installs the latest pre-release, 1.0.0rc2.
Your first query
Save this as check.py. It connects to the service the quickstart started and queries the demo namespace:
Run it:
The quickstart service has no authentication, so there’s no api_key here. To connect to a service that requires one, use Cortrix(base_url=..., api_key="your-cortrix-api-key").
If every call raises CortrixError with status code 502 while curl to the same address works, a system proxy is usually intercepting requests to your own machine. Bypass the proxy for local addresses and try again:
Client options
| Option | Purpose |
|---|---|
base_url | The service address. Defaults to http://localhost:8420 |
api_key | An API key. Optional |
tenant_id | A tenant identifier. Optional |
timeout | The request timeout |
max_retries | The maximum number of automatic retries |
http_client | Pass in your own httpx.Client |
client_id | Sent as the X-Client-Id header to tell callers apart |
trace_id_provider | A function that returns a W3C traceparent, for distributed tracing |
Query
client.search() maps to POST /query. The first argument can be a single namespace, a list of namespaces, or ["*"] for all of them:
| Parameter | Default | Purpose |
|---|---|---|
top_k | 10 | How many results to return |
rerank | True | Whether to rerank |
include_sources | False | Whether to return source information |
filters | None | Filter conditions |
coverage_ratio, namespaces_succeeded, and namespaces_failed in results.meta tell you whether a cross-namespace query fully succeeded.
Upload documents
Uploads are processed asynchronously and return a task. Track it with client.documents.status() or client.documents.task_progress().
Async client
The async client mirrors the sync client exactly. Every resource method has an async counterpart:
Resources
| Resource | Methods |
|---|---|
client.documents | upload, list, get, status, task_progress, cancel_task, delete |
client.namespaces | create, list, get, update, delete, set_permission |
client.search(...) | Semantic query |
client.memory | search, log, list, create, update, delete |
client.watchers | add, list, remove, events |
client.system | health, version, namespace_stats, agent_llm_config |
client.ops.gc | status, run, restore, purge |
client.import_database(...) In development | Start a database import manually |
client.tenants In development | list, get, invite, update_role, quota, create |
Resources marked In development have no documentation yet.
Handle errors
Every exception derives from CortrixError and carries structured fields, so you can decide whether to retry or report:
The SDK retries automatically using the server’s hints. To decide whether to retry, it looks at the retryable field first and then at the HTTP status code. For the wait time it uses retry_after_ms, then the Retry-After header, then exponential backoff. Adjust the number of attempts with max_retries.
Operations
Runtime and maintenance operations live under client.ops:
client.ops.gc.run() and client.ops.gc.purge() are destructive. purge() deletes data permanently and can’t be undone.
Next steps
4 - Framework adapters
On this page you’ll install cortrix-skills, call its tools directly, and turn them into tool definitions that Claude, OpenAI, or LangChain understand.
cortrix-skills provides a CortrixToolKit with 29 methods that map one-to-one to the MCP server’s regular tools, with the same names and semantics. Three adapters turn the toolkit into each framework’s native tool format, so you don’t write tool glue by hand. Admin tools are out of scope for this package.
Prerequisites
- A running Cortrix service. See the Quickstart.
- Python 3.9 or later, in a virtual environment.
Install
Install the package from PyPI. It brings in the Python SDK as a dependency:
The framework SDKs are optional dependencies. Building Claude or OpenAI tool definitions needs no framework SDK at all, because the definitions are plain JSON. Install a framework’s package when you need it, for example pip install anthropic.
Call the tools directly
CortrixToolKit is lazy: it makes no network request until you call a method.
| Parameter | Default | Description |
|---|---|---|
base_url | — | Required unless you pass client |
api_key | None | A Cortrix API key |
default_namespace | "default" | Used when a method doesn’t name a namespace |
client | — | Pass in an existing cortrix.Cortrix client |
Connect a framework
The three examples below come from cortrix-skills/README.md in the repository. They need a key for the matching LLM service, and the full round trip with a model hasn’t been tested for this page.
Claude Tools
OpenAI function calling
LangChain
Error handling
Cortrix errors pass through unchanged from the Python SDK. This package adds no error codes of its own. Every error carries code, retryable, category, retry_after_ms, and structured_data, and each adapter surfaces them in its framework’s native shape:
| Framework | How an error appears |
|---|---|
| LangChain | A ToolException whose message is these fields as JSON |
| Claude Tools | A tool_result with is_error=True whose content is these fields as JSON |
| OpenAI | These fields as JSON, returned as the tool message content |
An agent can use them to decide for itself whether to retry, wait, or report, without parsing free text.
Next steps
- MCP server: the full list of tools.
- Python SDK
5 - Built-in Agent
The built-in Agent is a FastAPI service that provides fixed-flow RAG chat over Cortrix storage. It queries cortrix-server through the public Python SDK and has no privileged channel:
The setup steps and interface details on this page come from cortrix-agent/README.md in the repository. The built-in Agent needs a working LLM service, and it hasn’t been tested for this page. The quickstart leaves the built-in Agent off by default.
Current scope
The built-in Agent has one mode: chat, a fixed RAG flow with no autonomous tool selection. It’s in preview.
Persisting configuration through PUT /config/agent_llm hasn’t been verified for this documentation.
Prerequisites
- A running Cortrix service.
- Python 3.
- Credentials for an LLM service, for the
agent_llmrole.
Start the service
Put your LLM service configuration in .env. Keep real keys only in ignored local files such as .env, and don’t commit them.
Health check
The expected response shape:
In v1.0.0-rc.2, cortrix_server is always "unknown": this endpoint doesn’t check the Cortrix server. Use the server’s own readiness endpoint for that. If llm_reachable is false, check the LLM service configuration.
Chat interface
POST /chat streams the answer over server-sent events:
| Input | Location | Notes |
|---|---|---|
message | Request body | The user message |
session_id | Request body | An optional session identifier |
Authorization | Header | An optional Bearer token, depending on the server’s authentication mode |
X-Cortrix-Tenant-Id | Header | An optional tenant identifier |
X-Cortrix-Namespace | Header | Optional. Names the namespace |
explain=true | Query parameter | Returns extra explanation metadata |
debug=true | Query parameter | Returns more detail on failure |
Example SSE frames:
Errors come back as structured SSE error events with a code, a message, retryability, a category, an optional retry delay, and structured data.
Other endpoints
| Endpoint | Purpose |
|---|---|
GET /sessions/{id} | Returns the recent turns a session keeps in memory |
GET /config | Returns the current LLM configuration with the API key masked |
GET /config/providers | Returns the LLM provider catalog used by the configuration UI |
PUT /config/agent_llm | Updates the LLM configuration. Persisting it isn’t a verified capability yet |
GET /health | Returns service status, backend reachability, and LLM reachability |
Next steps
- Choose an access path
- Configuration: configure LLMs by role.
- Compatibility and status
6 - pgcortrix
In development. Not supported yet.
What to do instead
Call Cortrix from your application with the HTTP API or the Python SDK.