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

> Easily add custom MCP servers to your Codebuff agents. Learn how to configure mcp.json files or AgentDefinitions for seamless integration and enhanced agent capabilities.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: how-to-guide
- Published: 2026-03-08

---

**You can add custom MCP servers to agents in Codebuff by creating an [`mcp.json`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/cwd/.agents/mcp.json) (project-level)
2. [`../.agents/mcp.json`](https://github.com/CodebuffAI/codebuff/blob/main/../.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`](https://github.com/CodebuffAI/codebuff/blob/main/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:

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

```

### Step 2: Declare Your MCP Server Configuration

Each entry in [`mcp.json`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/agents/load-mcp-config.ts) (lines 52-67).

Here is a complete example configuring a Notion integration:

```json
{
  "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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/agents/types/agent-definition.ts) (lines 18-20) specifies this optional map.

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

```typescript
// .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`](https://github.com/CodebuffAI/codebuff/blob/main/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:

```typescript
// 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`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/agents/load-mcp-config.ts) | Core loader that discovers [`mcp.json`](https://github.com/CodebuffAI/codebuff/blob/main/mcp.json) files, merges configurations across the three search locations, and resolves environment variables via `resolveMcpEnv`. |
| [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/mcp.json) format, search order, and usage examples. |

## Summary

- **Global configuration**: Place an [`mcp.json`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/mcp.json); they resolve at load time via `resolveMcpEnv` in [`sdk/src/agents/load-mcp-config.ts`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/agents/load-mcp-config.ts) (lines 52-67). When you prefix a value with `$` in your [`mcp.json`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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.