How to Add Custom MCP Servers to Agents in Codebuff: A Complete Guide

You can add custom MCP servers to agents in Codebuff by creating an mcp.json file in a .agents directory for global access, or by attaching the mcpServers field directly to a specific AgentDefinition.

Codebuff leverages the Model Context Protocol (MCP) to enable agents to interact with external APIs, databases, and services. Whether you need a global integration available to every agent or a specialized tool for a single workflow, the repository provides flexible configuration options through JSON configuration files and TypeScript agent definitions.

Understanding MCP Server Scopes in Codebuff

Codebuff supports two distinct scopes for MCP server configuration:

• Global scope: Servers defined in mcp.json files are automatically loaded and available to every agent in the environment.
• Per-agent scope: Servers attached to a specific AgentDefinition via the mcpServers property are isolated to that agent and override any global configuration with the same name.

This dual-scope architecture allows you to maintain baseline integrations across your project while granting specific agents privileged access to sensitive services.

Step-by-Step Guide to Adding Custom MCP Servers

Step 1: Create the mcp.json Configuration File

Codebuff automatically discovers and loads files named mcp.json located in .agents directories. The loader searches three locations in the following order, with later locations overriding earlier ones:

1. cwd/.agents/mcp.json (project-level)
2. ../.agents/mcp.json (parent directory)
3. ~/.agents/mcp.json (user home directory)

According to the source code in sdk/src/agents/load-mcp-config.ts (lines 95-100), this cascading approach allows project-specific configurations to shadow global defaults.

Create your configuration file at the appropriate level:

mkdir -p .agents
touch .agents/mcp.json

Step 2: Declare Your MCP Server Configuration

Each entry in mcp.json maps a server name to an MCP configuration object following the standard MCP schema. You can define local command-based servers or remote HTTP/SSE endpoints.

Environment variables are supported using the $ prefix and are resolved at load time by the resolveMcpEnv function in sdk/src/agents/load-mcp-config.ts (lines 52-67).

Here is a complete example configuring a Notion integration:

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

Step 3: Attach Servers to Agents

For global access: Simply place the server definition in mcp.json as shown above. Every agent will automatically have access to these tools.

For per-agent access: Import the AgentDefinition type and include the mcpServers field in your agent definition file. The type definition in agents/types/agent-definition.ts (lines 18-20) specifies this optional map.

Per-agent configurations override global ones with the same server name.

// .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 workspaces',
  inputSchema: {
    prompt: { type: 'string', description: 'Question about your Notion workspace' },
  },
  mcpServers: {
    notionApi: {
      command: 'npx',
      args: ['-y', '@notionhq/notion-mcp-server'],
      env: { NOTION_TOKEN: '$NOTION_TOKEN' },
    },
  },
  systemPrompt: `You are a Notion expert...`,
}

export default definition

Invoking MCP Tools from Agent Code

When an agent executes a tool, the runtime resolves the server configuration from agentTemplate.mcpServers. In packages/agent-runtime/src/tools/tool-executor.ts (lines 483-490), the tool name is split on the / character to separate the server prefix from the tool identifier.

Use the syntax serverName/toolName to target a specific server:

// Inside a handleSteps generator
const { toolResult } = yield {
  toolName: 'notionApi/searchPages',
  input: { query: 'project roadmap' },
}

If you omit the server prefix, the runtime searches across all loaded MCP servers to find a matching tool name.

Key Implementation Files in the Codebuff Repository

Understanding the source code helps debug configuration issues and extend functionality:

File	Purpose
sdk/src/agents/load-mcp-config.ts	Core loader that discovers mcp.json files, merges configurations across the three search locations, and resolves environment variables via resolveMcpEnv.
agents/types/agent-definition.ts	TypeScript definitions for AgentDefinition, including the optional mcpServers field for per-agent configuration.
packages/agent-runtime/src/tools/tool-executor.ts	Runtime execution logic that parses tool names, resolves server configurations, and routes calls to the appropriate MCP server.
web/src/content/tips/mcp-servers.mdx	Documentation covering the mcp.json format, search order, and usage examples.

Summary

• Global configuration: Place an mcp.json file in .agents/ at the project, parent, or home directory level to make MCP servers available to all agents.
• Per-agent configuration: Add the mcpServers field to an AgentDefinition to restrict server access to specific agents and override global settings.
• Environment variables: Reference env vars with $VAR_NAME in mcp.json; they resolve at load time via resolveMcpEnv in sdk/src/agents/load-mcp-config.ts.
• Tool invocation: Use the serverName/toolName syntax when calling tools to target specific MCP servers, or omit the prefix to search all servers.

Frequently Asked Questions

Can I use the same MCP server name in both global and per-agent configurations?

Yes, but the per-agent configuration takes precedence. According to the AgentDefinition type in agents/types/agent-definition.ts, the mcpServers field overrides any globally loaded server with the same key. This allows you to customize server parameters for specific agents while maintaining a default configuration for others.

How does Codebuff handle environment variables in MCP server configurations?

Codebuff resolves environment variables at configuration load time using the resolveMcpEnv function located in sdk/src/agents/load-mcp-config.ts (lines 52-67). When you prefix a value with $ in your mcp.json file, the loader substitutes it with the corresponding environment variable value. If the variable is undefined, the configuration may fail to load depending on the server's requirements.

What is the search order for mcp.json files, and how do overrides work?

The loader searches three locations in sequence: first the current working directory (cwd/.agents), then the parent directory (../.agents), and finally the user home directory (~/.agents). As documented in sdk/src/agents/load-mcp-config.ts (lines 95-100), configurations found in later locations override those from earlier ones. This cascading approach lets you define user-wide defaults while allowing project-specific overrides.

How do I call a tool from a specific MCP server in my agent code?

Use the namespaced syntax serverName/toolName when specifying the tool name in your agent's step generator. The runtime logic in packages/agent-runtime/src/tools/tool-executor.ts (lines 483-490) splits the string on the / character to identify the server and tool. If you omit the server prefix, the runtime searches across all loaded MCP servers to find a matching tool name, which may result in ambiguity if multiple servers expose tools with identical names.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}