MCP servers

Spawn any Model Context Protocol server at startup; its tools are wired in automatically.

What MCP is

The Model Context Protocol is an open standard for exposing tools, resources and prompts to LLMs. An MCP server is a process that speaks the protocol — GitHub's server, a filesystem server, a database server, anything.

Configuring a server

mcp_servers:
  github:
    command: docker
    args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]
    env: ["GITHUB_TOKEN=ghp_..."]

Each entry under mcp_servers names a server and gives the command, arguments and environment to spawn it. cortex starts the server at startup, discovers its tools over the protocol, and wires them into the agent's tool set.

Auto-discovery

You don't enumerate the tools a server provides — cortex asks the server what it offers and adds every tool to the catalog automatically. If the server adds a new tool, it shows up on the next session with no config change.

Environment variables

The env list is passed to the spawned process. Use it for API tokens and any other secrets the server needs. The values are strings; a leading $ doesnot expand here (unlike api_key), so pass the literal value or interpolate from your shell before writing the config.

⚠️

Security: an MCP server runs with the same filesystem and network access as the cortex process. Only spawn servers you trust.

Multiple servers

mcp_servers:
  github:
    command: docker
    args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]
    env: ["GITHUB_TOKEN=..."]
  sqlite:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"]

Tools from all servers are merged into a single catalog. Name collisions are resolved by the server prefix.

📖

MCP is axon's. cortex spawns the servers in config; axon speaks the protocol, discovers the tools, and merges them with its built-in toolsinto one catalog. The auto-discovery is axon's — seeaxon's tools reference for the full toolset cortex gets on top of MCP.