MCP servers

This topic describes how to extend the Cortex Code Agent SDK with external MCP (Model Context Protocol) servers. MCP servers let your agent call external tools alongside built-in tools like Read, Edit, and Bash.

Overview

The current Cortex runtime supports external MCP servers over these transports:

  • stdio

  • http

  • sse

Connecting external MCP servers

Stdio servers

Stdio servers are external processes that communicate over standard input and output.

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "Search our docs for authentication best practices",
  options: {
    cwd: process.cwd(),
    permissionMode: "bypassPermissions",
    allowDangerouslySkipPermissions: true,
    mcpServers: {
      "my-tools": {
        command: "node",
        args: ["my-mcp-server.js"],
      },
    },
  },
})) {
  // Handle messages...
}

HTTP and SSE servers

For remote MCP servers that communicate over HTTP or Server-Sent Events (SSE):

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "Look up customer data",
  options: {
    cwd: process.cwd(),
    permissionMode: "bypassPermissions",
    allowDangerouslySkipPermissions: true,
    mcpServers: {
      "remote-api": {
        type: "http",
        url: "https://my-mcp-server.example.com/mcp",
        headers: { "Authorization": "Bearer ${MCP_TOKEN}" },
      },
    },
  },
})) {
  // Handle messages...
}

You can also use "type": "sse" for servers that use SSE transport.

Controlling which MCP tools are allowed

MCP tools are namespaced with the mcp__ prefix in the format mcp__<server-name>__<tool-name>. Use the allowedTools (TypeScript) or allowed_tools (Python) option to control which tools the agent can call:

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "Search our documentation",
  options: {
    cwd: process.cwd(),
    permissionMode: "bypassPermissions",
    allowDangerouslySkipPermissions: true,
    allowedTools: [
      "mcp__my-tools__search_docs",
      "mcp__my-tools__*",
    ],
    mcpServers: {
      "my-tools": { command: "node", args: ["my-mcp-server.js"] },
    },
  },
})) {
  // Handle messages...
}

You can also use disallowedTools / disallowed_tools to block specific tools.

Disabling MCP

To disable all MCP servers for a session, use the noMcp (TypeScript) or no_mcp (Python) option:

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  noMcp: true,
});

Feature comparison

Feature

Python

TypeScript

External MCP servers (stdio)

Yes (mcp_servers)

Yes (mcpServers)

External MCP servers (HTTP/SSE)

Yes (mcp_servers)

Yes (mcpServers)

allowedTools / allowed_tools

Yes

Yes

noMcp / no_mcp

Yes

Yes