MCP Configuration

MCP (Model Context Protocol) enables agents to use external tool servers.

Configuration File

MCP servers are configured in .pantheon/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Server Configuration

Each server entry has:

Field	Description
command	Executable to run (e.g., npx, python, node)
args	Command arguments as array
env	Environment variables (supports ${VAR} substitution)
cwd	Working directory for the server

Common MCP Servers

Filesystem Server

Access local files:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "."]
    }
  }
}

GitHub Server

GitHub operations:

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

PostgreSQL Server

Database operations:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Puppeteer Server

Browser automation:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-puppeteer"]
    }
  }
}

Custom Python Server

{
  "mcpServers": {
    "custom": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "cwd": "/path/to/server"
    }
  }
}

Using MCP in Templates

In Agent Templates

---
name: GitHub Assistant
model: openai/gpt-4o
mcp_servers:
  - github
  - filesystem
---

You are a GitHub assistant.

In Team Templates

---
name: Dev Team
agents:
  - name: developer
    mcp_servers:
      - github
      - filesystem
    instructions: Write and commit code.
---

Using MCP in Python API

from pantheon.agent import Agent
from pantheon.providers import MCPProvider

# Create agent
agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant."
)

# Add MCP provider at runtime
await agent.mcp(
    name="filesystem",
    provider=MCPProvider("npx -y @anthropic/mcp-server-filesystem .")
)

response = await agent.run("List files in current directory")

Environment Variables

Use ${VAR} syntax for environment variable substitution:

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "db_server"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

Variables are resolved from:

1. Process environment

2. .env file in project root

3. Shell environment

Server Lifecycle

MCP servers are:

1. Started on demand when an agent with that server is created

2. Kept running for the session duration

3. Stopped when the session ends or explicitly disconnected

Multiple Usage

The same MCP server can be used by multiple agents:

{
  "mcpServers": {
    "shared-fs": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "."]
    }
  }
}

---
name: Team
agents:
  - name: reader
    mcp_servers: [shared-fs]
    instructions: Read files.
  - name: writer
    mcp_servers: [shared-fs]
    instructions: Write files.
---

Troubleshooting

Server Not Starting

Check:

1. Command is installed (npx, python, etc.)

2. Package exists (npm install -g @anthropic/mcp-server-xxx)

3. Environment variables are set

View Logs

Enable debug logging:

export PANTHEON_LOG_LEVEL=DEBUG
pantheon cli

Connection Issues

If a server fails to connect:

1. Test the command manually in terminal

2. Check for port conflicts

3. Verify environment variables

4. Check server-specific requirements

Finding MCP Servers

• Anthropic MCP Servers

• MCP Server Registry

• Community servers on GitHub

Creating Custom Servers

See the MCP Specification for creating your own servers.

Basic Python server:

from mcp import Server, Tool

server = Server("my-server")

@server.tool
def my_tool(param: str) -> str:
    """Tool description."""
    return f"Result: {param}"

if __name__ == "__main__":
    server.run()