MCP — Model Context Protocol

Wire external tools into the agent. anyclaude-sdk loads tools from remote MCP servers (HTTP/SSE) and in-process SDK servers (plain JS, no subprocess), wrapping each as a native tool. Pass them via query({ mcpServers }).

External MCP servers (HTTP / SSE)

Configure remote servers by name. Each entry sets a type ('http' or 'sse'), a url, and optional headers (e.g. auth). Their tools are discovered on connect and exposed to the model namespaced as mcp__<server>__<tool>.

import { query } from 'anyclaude-sdk'

await query({
  prompt: 'Search the docs and summarize the auth flow.',
  workspace, llm,
  mcpServers: {
    docs: { type: 'http', url: 'https://mcp.example.com/mcp', headers: { Authorization: 'Bearer …' } },
    events: { type: 'sse', url: 'https://mcp.example.com/sse' },
  },
})
// Model sees tools like: mcp__docs__search, mcp__events__subscribe

Loading never throws: a server that fails to connect simply contributes no tools and a failed status. Per-server connection status is surfaced on the system init message (mcp_servers), so you can show it in your UI.

In-process SDK servers

Define MCP tools in plain JavaScript that run in the same process as the agent — no network, no transport. Build them with tool() and group them with createSdkMcpServer(), then pass under mcpServers. They appear to the model as mcp__<name>__<tool> too.

import { query, createSdkMcpServer, tool } from 'anyclaude-sdk'

const math = createSdkMcpServer({
  name: 'math',
  tools: [
    tool(
      'add',
      'Add two numbers',
      { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
      async ({ a, b }) => ({ content: [{ type: 'text', text: String((a as number) + (b as number)) }] }),
    ),
  ],
})

await query({ prompt, workspace, llm, mcpServers: { math } })
// → mcp__math__add

An SDK tool's handler returns MCP content blocks (text, image, resource, …); the SDK maps them into the agent's result blocks (images come through natively).

CORS proxy (for the browser)

Browsers block direct cross-origin fetches to most MCP servers (no permissive CORS). Route remote MCP requests through a proxy you control with mcpProxy. Not needed in Node/Bun or for in-process SDK servers.

await query({
  prompt, workspace, llm,
  mcpServers: { docs: { type: 'http', url: 'https://mcp.example.com/mcp' } },
  // Any of these forms:
  mcpProxy: 'https://my-proxy.example/?u={url}',   // {url} → URL-encoded target
  // mcpProxy: 'https://my-proxy.example/{rawUrl}', // {rawUrl} → raw target
  // mcpProxy: 'https://my-proxy.example/',         // bare prefix (raw appended)
  // mcpProxy: (target) => `https://my-proxy.example/?u=${encodeURIComponent(target)}`,
})

The proxy must forward the request (method, body, and headers — including Mcp-Session-Id and Content-Type) to the target, then echo permissive CORS headers and the Mcp-Session-Id response header back.