MCP (Model Context Protocol)

Canonical contract: packages/sdk/docs.md — mcpServers option, OAuth flow.

Model Context Protocol is an open standard for connecting AI agents to data sources and tools. The SDK is a first-class MCP client.

Stdio servers (local processes)

Most MCP servers ship as npx-runnable Node processes:

const agent = await Agent.create({
  apiKey, model,
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
    },
    puppeteer: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-puppeteer"],
    },
  },
});

The SDK spawns each server, discovers its tools/resources/prompts, and exposes them to the agent loop. On dispose(), all child processes are terminated.

HTTP servers (remote)

For remote MCP servers (e.g. SaaS APIs):

mcpServers: {
  notion: {
    type: "http",
    url: "https://mcp.notion.com",
    headers: { Authorization: `Bearer ${process.env.NOTION_TOKEN}` },
  },
}

OAuth 2.1 PKCE (remote SaaS APIs)

For MCP servers that require OAuth (e.g. Notion, Linear), the SDK ships a PKCE flow:

pnpm exec theokit-mcp-auth-notion --setup

This walks the user through browser auth, stores the token in OS keychain (fallback: ~/.theokit/mcp-tokens.json with 0600 perms — ADR D41), and the agent picks it up automatically:

mcpServers: {
  notion: {
    type: "http",
    url: "https://mcp.notion.com",
    oauth: { provider: "notion" },
  },
}

See the mcp-oauth-notion example.

MCP config files

Beyond inline config, the SDK reads .theokit/mcp.json (project) and ~/.theokit/mcp.json (user). Project entries override user entries by key. See Configuration.

Configuration reference

type McpServerConfig =
  | { command: string; args?: string[]; env?: Record<string, string> } // stdio
  | { type: "http"; url: string; headers?: Record<string, string>; oauth?: McpOauthConfig };

API reference