Skip to main content
Version: Next

MCP Server

Cortex 3.2 includes an MCP (Model Context Protocol) server that allows compatible AI agents and systems to interact with your Cortex archives. Through the MCP endpoint, AI agents can query, search, create, update, and delete records, execute data-source-specific actions, and run user-authored Cortex Actions.

How It Works​

The MCP server uses the Streamable HTTP transport, which means it works over standard HTTP without requiring server-sent events (SSE) or long-lived connections. This makes it compatible with a wide range of AI agents and MCP clients, including Claude, OpenCode, and custom agent frameworks.

The endpoint is available at:

http://YOUR_CORTEX_URL/mcp

Enabling MCP Access​

MCP access is controlled through several administrative settings:

1. Global Enable/Disable​

Navigate to Admin → API → MCP Server to toggle the MCP server on or off globally. This setting controls whether the /mcp endpoint responds at all.

When the MCP server is enabled, the admin page shows its current status and provides access to audit logging settings.

2. API Key Configuration​

Each API key can be granted MCP access individually:

  • MCP Access — enable or disable MCP access for this key
  • MCP Mode — choose between:
    • ReadOnly — the key can only use discovery and query tools (list tables, search records, get records, etc.)
    • ReadWrite — the key can also create, update, and delete records, and execute actions

3. Data Source Exposure​

Each data source can be individually enabled or disabled for MCP access. This lets you control which archives are visible to AI agents.

4. Cortex Action Exposure​

User-authored Cortex Actions can be individually marked as Expose over MCP. When enabled, the action appears as its own dedicated MCP tool with an input schema generated from its parameter contract.

Available MCP Tools​

Generic Tools (Always Available)​

These tools are available for every data source that has MCP access enabled:

Tier 1 — Discovery & Query (ReadOnly mode):

  • list_data_sources — list all data sources with MCP access enabled
  • list_tables — list tables in a data source
  • describe_table — describe a table's schema
  • search_records — search records in a data source
  • get_record — get a single record by ID
  • list_relationships — list relationships for a record

Tier 2 — Writes (ReadWrite mode only):

  • create_record — create a new record
  • update_record — update an existing record
  • delete_record — delete a record
  • add_note — add a note to a record

Tier 3 — Data Source Actions (ReadWrite mode only):

  • list_data_source_actions — list available data-source-specific actions
  • execute_data_source_action — execute a data-source-specific action

Tier 4 — Cortex Actions (ReadWrite mode only):

  • list_cortex_actions — list user-authored Cortex Actions
  • run_cortex_action — run a Cortex Action

Per-Action Dedicated Tools​

When a Cortex Action has the Expose over MCP checkbox checked, it appears as its own dedicated MCP tool with the name cortex_action_<sanitized_name>. The tool's input schema is automatically generated from the action's parameter contract, making it easy for AI agents to discover and use the right parameters.

Authentication​

MCP clients authenticate using the standard MCP bearer token header. The token is an API key with MCP Access enabled (see API Key Configuration above).

Audit Logging​

MCP access can be audited for security and compliance. When audit logging is enabled (from Admin → API → MCP Server → Audit Logging):

  • All write operations are recorded as audit log entries
  • All action executions are recorded
  • All denied access attempts (e.g., a ReadOnly key attempting a write operation) are recorded
  • Each entry includes the tool name, API key identity, outcome, and structured detail

Audit logs are visible in Admin → View Logs and are always visible regardless of the global log level setting.

MCP Clients​

Any MCP-compatible client can connect to Cortex's MCP endpoint. Common clients include:

  • Claude (Anthropic) — connect via the MCP integration
  • OpenCode — configure the MCP server in your .opencode/mcp.json configuration
  • Custom agents — connect using the Model Context Protocol SDK for your language

Example MCP configuration for a client:

{
  "mcpServers": {
    "cortex": {
      "type": "streamable-http",
      "url": "https://YOUR_CORTEX_URL/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Read-Only Mode​

When an API key is configured with ReadOnly MCP mode, it can only access Tier 1 (discovery and query) tools. Any attempt to use write, data-source-action, or Cortex-Action tools will be denied with an error message before any data source lookup occurs. Denied attempts are logged if audit logging is enabled.