MCP Servers

The Model Context Protocol (MCP) is an open standard that lets you connect AI agents to external tools and data sources.

Add MCP tools with a mcp.json file in your .agents/ directory. Servers configured here are automatically available to all base agents.

Create .agents/mcp.json:

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

Set your NOTION_TOKEN environment variable and start Vesper Code — Notion tools are now available.

1. Run /init within Vesper Code to set up your .agents directory
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 Vesper Code

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

1. {cwd}/.agents/mcp.json — Project-specific
2. {cwd}/../.agents/mcp.json — Parent directory (monorepos)
3. ~/.agents/mcp.json — Global

{
  "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"
      }
    }
  }
}

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

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

Or use a .env file in your project root.

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

MCP tools not appearing: Check that mcp.json is valid JSON, verify it's in .agents/mcp.json, and restart Vesper Code.

Environment variable not found: Ensure the variable is exported in your shell and restart your terminal after adding to .bashrc/.zshrc.

Server not connecting: Run the MCP server command manually to test it works.