MCP 服务器

本主题介绍如何通过外部 MCP（模型上下文协议）服务器来扩展 Cortex Code Agent SDK。借助 MCP 服务器，您的代理可以调用调用外部工具以及内置工具，例如 Read、Edit 和 Bash。

概述

当前 Cortex 运行时支持通过以下传输方式访问外部 MCP 服务器：

  • stdio

  • http

  • sse

连接外部 MCP 服务器

Stdio 服务器

Stdio 服务器是通过标准输入和输出进行通信的外部进程。

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 和 SSE 服务器

对于通过 HTTP 或服务器发送的事件 (SSE) 进行通信的远程 MCP 服务器：

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...
}

对于使用 SSE 传输方式的服务器，您也可以使用 "type": "sse"。

控制允许使用哪些 MCP 工具

MCP 工具的命名遵循统一前缀 mcp__，格式为 mcp__<server-name>__<tool-name>。使用 allowedTools (TypeScript) 或 allowed_tools (Python) 选项，可控制代理可以调用哪些工具：

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...
}

您还可以使用 disallowedTools / disallowed_tools 来拦截特定的工具。

禁用 MCP

若要在一个会话中禁用所有 MCP 服务器，请使用 noMcp (TypeScript) 或 no_mcp (Python) 选项：

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

功能比较

功能

Python

TypeScript

外部 MCP 服务器 (stdio)

是 (mcp_servers)

是 (mcpServers)

外部 MCP 服务器 (HTTP/SSE)

是 (mcp_servers)

是 (mcpServers)

allowedTools / allowed_tools

是

是

noMcp / no_mcp

是

是