Skip to content

Choose an access path

Compare the HTTP API, MCP, the Python SDK, and the built-in Agent.

Cortrix has four access paths. This page helps you pick the one that fits your situation.

How to choose

Your situationChoose
You need precise control over requests, retries, authentication, and deployment, or you’re not using PythonHTTP API
You want an agent in your IDE, or another MCP-compatible client, to call CortrixMCP server
You’re writing a Python application, a RAG pipeline, or a test scriptPython SDK
You want local fixed-flow chat over what’s in Cortrix, without wiring up an agent frameworkBuilt-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:

curl -fsS http://127.0.0.1:8420/api/v1/system/health/ready

Run a query:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["demo"],
    "query": "What does semantic storage keep close to the agents that need it?",
    "top_k": 5,
    "rerank": true
  }' \
  http://127.0.0.1:8420/api/v1/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