MCP 서버

MCP 서버

이 항목에서는 외부 MCP(Model Context Protocol) 서버로 Cortex Code Agent SDK를 확장하는 방법을 설명해요. MCP 서버는 에이전트가 Read, Edit, Bash 같은 기본 제공 도구와 함께 외부 도구를 호출할 수 있게 해줘요.

출처: MCP servers

본문

현재 Cortex 런타임은 다음 전송(transport)을 통해 외부 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...
}

from cortex_code_agent_sdk import query, CortexCodeAgentOptions

async for message in query(
    prompt="Search our docs for authentication best practices",
    options=CortexCodeAgentOptions(
        permission_mode="bypassPermissions",
        allow_dangerously_skip_permissions=True,
        mcp_servers={
            "my-tools": {
                "command": "node",
                "args": ["my-mcp-server.js"],
            },
        },
    ),
):
    # Handle messages...
    pass

HTTP 및 SSE 서버

HTTP 또는 Server-Sent Events(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...
}

from cortex_code_agent_sdk import query, CortexCodeAgentOptions

async for message in query(
    prompt="Look up customer data",
    options=CortexCodeAgentOptions(
        permission_mode="bypassPermissions",
        allow_dangerously_skip_permissions=True,
        mcp_servers={
            "remote-api": {
                "type": "http",
                "url": "https://my-mcp-server.example.com/mcp",
                "headers": {"Authorization": "Bearer ${MCP_TOKEN}"},
            },
        },
    ),
):
    # Handle messages...
    pass

SSE 전송을 사용하는 서버에는 "type": "sse"를 사용할 수도 있어요.

허용되는 MCP 도구 제어

MCP 도구는 mcp__<server-name>__<tool-name> 형식의 이름에 mcp__ 접두사가 붙어요. 에이전트가 호출할 수 있는 도구를 제어하려면 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...
}

from cortex_code_agent_sdk import query, CortexCodeAgentOptions

async for message in query(
    prompt="Search our documentation",
    options=CortexCodeAgentOptions(
        permission_mode="bypassPermissions",
        allow_dangerously_skip_permissions=True,
        allowed_tools=[
            "mcp__my-tools__search_docs",
            "mcp__my-tools__*",
        ],
        mcp_servers={
            "my-tools": {"command": "node", "args": ["my-mcp-server.js"]},
        },
    ),
):
    # Handle messages...
    pass

특정 도구를 차단하려면 disallowedTools / disallowed_tools를 사용할 수도 있어요.

MCP 비활성화

세션의 모든 MCP 서버를 비활성화하려면 noMcp(TypeScript) 또는 no_mcp(Python) 옵션을 사용해요.

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

options = CortexCodeAgentOptions(no_mcp=True)

기능 비교

더 알아보기

• Cortex Code Agent SDK
• Hooks
• TypeScript reference