MCP Servers

The Model Context Protocol (MCP) is an open standard that lets you connect AI agents to external tools and data sources. Codebuff agents can use MCP servers to access APIs, databases, and other services.

The easiest way to add MCP tools to Codebuff is with a mcp.json file in your .agents/ directory. MCP servers configured here are automatically available to all base agents (base2, base2-max, etc.).

Create .agents/mcp.json:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "$NOTION_TOKEN"
      }
    }
  }
}

That's it! Now Codebuff can query your Notion workspace. Just set your NOTION_TOKEN environment variable and start using Notion tools in any conversation.

1. Run /init within Codebuff to set up your .agents directory (if you haven't already)
2. Create .agents/mcp.json with your MCP server configuration
3. Set any required environment variables (e.g., export NOTION_TOKEN="your-token")
4. Start Codebuff — the MCP tools are now available!

Codebuff searches for mcp.json in these locations (later ones override earlier):

1. {cwd}/.agents/mcp.json — Project-specific MCP servers
2. {cwd}/../.agents/mcp.json — Parent directory (useful for monorepos)
3. ~/.agents/mcp.json — Global MCP servers available in all projects

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "$NOTION_TOKEN"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "myApi": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "$API_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "streamingApi": {
      "type": "sse",
      "url": "https://stream.example.com/mcp/events",
      "headers": {
        "X-API-Key": "$STREAM_API_KEY"
      },
      "params": {
        "workspace": "default"
      }
    }
  }
}

For more control, you can configure MCP servers directly on individual agents using the mcpServers field. This is useful when:

• You want MCP tools available only to a specific agent
• You're building a specialized agent that wraps MCP functionality
• You want to customize the agent's prompts around the MCP tools

.agents/notion-agent.ts

import type { AgentDefinition } from './types/agent-definition'

const definition: AgentDefinition = {
  id: 'notion-query-agent',
  displayName: 'Notion Query Agent',
  model: 'anthropic/claude-sonnet-4.5',

  spawnerPrompt:
    'Expert at querying Notion databases and pages to find information and answer questions about content stored in Notion workspaces.',

  inputSchema: {
    prompt: {
      type: 'string',
      description:
        'A question or request about information stored in your Notion workspace',
    },
  },

  outputMode: 'last_message',
  includeMessageHistory: false,

  mcpServers: {
    notionApi: {
      command: 'npx',
      args: ['-y', '@notionhq/notion-mcp-server'],
      env: {
        NOTION_TOKEN: '$NOTION_TOKEN',
      },
    },
  },

  systemPrompt: `You are a Notion expert who helps users find and retrieve information from their Notion workspace. You can search across pages and databases, read specific pages, and query databases with filters.`,

  instructionsPrompt: `Instructions:
1. Use the Notion tools to search for relevant information based on the user's question. Start with a broad search.
2. If you find relevant pages or databases, read them in detail or query them with appropriate filters
3. Provide a comprehensive answer based on the information found in Notion.
`,
}

export default definition

Reference your agent in the CLI using @ followed by the agent's display name:

@Notion Query Agent what meetings do I have this week?

Other agents can spawn your MCP-enabled agent if it's listed in their spawnableAgents:

spawnableAgents: ['notion-query-agent']

Runs an MCP server as a local process that communicates via stdin/stdout:

{
  "mcpServers": {
    "serverName": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@org/mcp-server"],
      "env": {
        "VAR_NAME": "$VAR_NAME"
      }
    }
  }
}

Fields:

• type ('stdio') — Optional. Indicates a local process server (default)
• command (string) — The command to execute (e.g., 'npx', 'node', 'python')
• args (string[]) — Arguments passed to the command
• env (object) — Environment variables for the MCP server process

Connects to a remote MCP server via HTTP or Server-Sent Events (SSE):

{
  "mcpServers": {
    "serverName": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "params": {
        "paramName": "value"
      },
      "headers": {
        "Authorization": "$API_TOKEN"
      }
    }
  }
}

Fields:

• type ('http' | 'sse') — Required. 'http' for standard HTTP, 'sse' for Server-Sent Events
• url (string) — The URL of the remote MCP server
• params (object) — Query parameters to include in requests
• headers (object) — HTTP headers to include in requests (e.g., for authentication)

Use the $VAR_NAME syntax to reference environment variables from your shell:

{
  "env": {
    "NOTION_TOKEN": "$NOTION_TOKEN",
    "API_KEY": "$MY_API_KEY"
  }
}

This reads NOTION_TOKEN and MY_API_KEY from your environment and passes them to the MCP server.

Setup: Add your token to your shell configuration (e.g., .bashrc, .zshrc):

export NOTION_TOKEN="your-notion-integration-token"

Or use a .env file in your project root.

Browse available MCP servers at:

• MCP Server Registry - Official and community servers
• NPM - Search for mcp-server packages

MCP tools not appearing:

• Check that mcp.json is valid JSON (no trailing commas, proper quoting)
• Verify the file is in .agents/mcp.json (not just .agents/)
• Restart Codebuff after adding or modifying mcp.json

Environment variable not found:

• Ensure the variable is exported in your shell
• Restart your terminal after adding to .bashrc/.zshrc
• Check for typos in the $VAR_NAME reference

Server not connecting:

• Verify the command and args are correct
• Run the MCP server command manually to test it works
• Check the server's documentation for required setup steps