MCP Servers

MCP (Model Context Protocol) servers extend your agents with custom tools and resources, enabling integration with external services like GitHub, PostHog, databases, and more.

What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI assistants to interact with external tools and data sources. MCP servers provide:

• Tools: Custom functions the agent can call (e.g., create GitHub issues, query databases)
• Resources: Data sources the agent can read (e.g., documentation, knowledge bases)
• Prompts: Predefined prompt templates

When you configure an MCP server for an agent, all tools from that server become available to the agent during its sessions.

---

Configuration

MCP servers are configured per-agent in the mcp_servers field. Each server has a unique name (key) and configuration.

Process-Based Servers

Most MCP servers run as local processes, spawned when the agent starts:

agents/coder.yaml

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

Field	Type	Description
type	string	Transport — stdio. Optional; inferred as stdio when no url is set
command	string	Executable to run
args	string[]	Command-line arguments
env	object	Environment variables (supports ${VAR} interpolation)
timeout	integer	Per-server tool-call timeout in milliseconds (values below 1000 are ignored)
alwaysLoad	boolean	Always include this server’s tools in the prompt instead of deferring them behind tool search

HTTP-Based Servers

Some MCP servers run as HTTP services:

mcp_servers:
  custom-api:
    url: http://localhost:8080/mcp

Field	Type	Description
type	string	Transport — http or sse. Optional; inferred as http when url is set
url	string	URL endpoint for the MCP server
headers	object	Request headers sent with every call — carries bearer / API-key auth
timeout	integer	Per-server tool-call timeout in milliseconds (values below 1000 are ignored)
alwaysLoad	boolean	Always include this server’s tools in the prompt instead of deferring them behind tool search

SSE and Authenticated Remote Servers

type is only inferred as http or stdio, never sse — a server that speaks Server-Sent Events must say so explicitly. Authentication for a remote server goes in headers:

mcp_servers:
  linear:
    type: sse
    url: https://mcp.linear.app/sse
    headers:
      Authorization: Bearer ${LINEAR_API_KEY}
    timeout: 30000

Set type and headers accurately

Claude Code files a remote server’s stored OAuth token under a key derived from {type, url, headers}. If a field is dropped or rewritten, the token is looked up under a different key and a previously-authorised server is no longer recognised — so it is not just auth-on-the-wire that breaks, it is the saved authorisation too.

camelCase is deliberate

alwaysLoad (and the rest of these fields) mirror the Agent SDK’s own McpServerConfig names rather than herdctl’s usual snake_case. Entries are passed through verbatim, so you can paste a block straight out of .mcp.json or ~/.claude.json.

---

Tool Naming Convention

MCP tools are namespaced using the mcp__<server>__<tool> pattern:

mcp__<server-name>__<tool-name>

For example, if you configure a server named github:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]

Its tools become available as:

• mcp__github__create_issue
• mcp__github__list_issues
• mcp__github__create_pull_request
• etc.

The server name in the tool identifier comes from the key you use in mcp_servers, not the package name.

---

Combining with Permissions

Use allowed_tools and denied_tools to control which MCP tools an agent can use.

Wildcard Support

Allow all tools from a specific server using wildcards:

allowed_tools:
  - Read
  - Write
  - Edit
  - mcp__github__*      # All GitHub MCP tools
  - mcp__posthog__*     # All PostHog MCP tools

Specific Tools Only

For tighter security, allow only specific tools:

allowed_tools:
  - Read
  - Write
  - mcp__github__list_issues
  - mcp__github__create_pull_request
  # Other GitHub tools are blocked

Denying Specific MCP Tools

Block specific tools while allowing others:

allowed_tools:
  - mcp__github__*
denied_tools:
  - mcp__github__delete_repository  # Block dangerous operations

Tip

denied_tools takes precedence over allowed_tools. A tool in both lists will be denied.

---

Common MCP Servers

GitHub Server

Access GitHub APIs for issues, PRs, repositories:

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

Tools provided:

• mcp__github__list_issues
• mcp__github__create_issue
• mcp__github__create_pull_request
• mcp__github__search_repositories
• And more…

Required environment:

export GITHUB_TOKEN=ghp_your_token_here

PostHog Server

Analytics and feature flag management:

mcp_servers:
  posthog:
    command: npx
    args: ["-y", "@anthropic/posthog-mcp-server"]
    env:
      POSTHOG_API_KEY: ${POSTHOG_API_KEY}
      POSTHOG_PROJECT_ID: ${POSTHOG_PROJECT_ID}

Tools provided:

• mcp__posthog__query-run
• mcp__posthog__feature-flag-get-all
• mcp__posthog__create-feature-flag
• mcp__posthog__experiment-create
• And more…

Required environment:

export POSTHOG_API_KEY=phx_your_api_key
export POSTHOG_PROJECT_ID=12345

Filesystem Server

Controlled filesystem access:

mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

Tools provided:

• mcp__filesystem__read_file
• mcp__filesystem__write_file
• mcp__filesystem__list_directory
• mcp__filesystem__create_directory
• And more…

The filesystem server restricts access to the specified directory path.

PostgreSQL Server

Database access:

mcp_servers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: ${DATABASE_URL}

Tools provided:

• mcp__postgres__query
• mcp__postgres__list_tables
• mcp__postgres__describe_table

Memory Server

Persistent memory/knowledge base:

mcp_servers:
  memory:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-memory"]

Tools provided:

• mcp__memory__store
• mcp__memory__retrieve
• mcp__memory__search

---

Full Examples

Development Agent with GitHub

A coder agent that can interact with GitHub issues and PRs:

name: dev-agent
description: "Implements features from GitHub issues"

repo: myorg/my-project
workspace: my-project

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

allowed_tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - mcp__github__*
  - "Bash(git *)"
  - "Bash(npm *)"
  - "Bash(pnpm *)"

Analytics Agent with PostHog

An agent that can query analytics and manage experiments:

name: analytics-agent
description: "Manages product analytics and experiments"

mcp_servers:
  posthog:
    command: npx
    args: ["-y", "@anthropic/posthog-mcp-server"]
    env:
      POSTHOG_API_KEY: ${POSTHOG_API_KEY}
      POSTHOG_PROJECT_ID: ${POSTHOG_PROJECT_ID}

allowed_tools:
  - Read
  - Glob
  - Grep
  - mcp__posthog__query-run
  - mcp__posthog__insights-get-all
  - mcp__posthog__feature-flag-get-all
  - mcp__posthog__experiment-get-all
denied_tools:
  - mcp__posthog__delete-feature-flag  # Block destructive operations
  - mcp__posthog__experiment-delete

Multi-Server Agent

An agent with access to multiple MCP servers:

name: full-stack-agent
description: "Full-stack development with multiple integrations"

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

  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace/docs"]

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

allowed_tools:
  - Read
  - Write
  - Edit
  - mcp__github__*
  - mcp__filesystem__*
  - mcp__postgres__query
  - mcp__postgres__list_tables
denied_tools:
  - mcp__postgres__*  # Then allow specific ones above

Custom MCP Server

Run your own MCP server implementation:

mcp_servers:
  internal-tools:
    command: node
    args: ["./mcp-servers/internal-tools.js"]
    env:
      API_KEY: ${INTERNAL_API_KEY}
      API_URL: https://api.internal.example.com

---

Server Lifecycle

MCP servers follow the agent session lifecycle:

1. Startup: When an agent session begins, herdctl spawns all configured MCP servers
2. Connection: Servers connect via stdio (process-based), HTTP, or SSE
3. Available: Tools become available for the agent to use
4. Shutdown: When the session ends, process-based servers are terminated

---

Environment Variables

MCP server configurations support environment variable interpolation using ${VAR} syntax:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}           # From shell environment
      GITHUB_ENTERPRISE_URL: ${GH_ENTERPRISE} # Custom variable

Set these in your shell or .env file before running herdctl.

---

Security Considerations

Principle of Least Privilege

Only grant access to tools an agent actually needs:

# Good: Specific tools
allowed_tools:
  - mcp__github__list_issues
  - mcp__github__create_pull_request

# Risky: All tools
allowed_tools:
  - mcp__github__*

Protect Sensitive Tokens

Never hardcode tokens in configuration:

# Bad
env:
  GITHUB_TOKEN: ghp_actualtoken123

# Good
env:
  GITHUB_TOKEN: ${GITHUB_TOKEN}

Limit Filesystem Access

When using the filesystem server, restrict to specific directories:

mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace/safe-dir"]
    # Agent can only access /workspace/safe-dir and subdirectories

Deny Destructive Operations

Block dangerous tools even when using wildcards:

allowed_tools:
  - mcp__github__*
denied_tools:
  - mcp__github__delete_repository
  - mcp__github__delete_branch

---

Debugging

Check MCP Server Status

# View logs including MCP server output
herdctl logs --agent my-agent

# Check if MCP servers started correctly
herdctl status --agent my-agent

Common Issues

Server fails to start:

• Check that the command is installed (npx, node, etc.)
• Verify environment variables are set
• Check for typos in package names

Tools not available:

• Verify the server name in mcp_servers matches the pattern in allowed_tools
• Check that the MCP server actually provides the expected tools
• Look for startup errors in agent logs

Authentication errors:

• Verify environment variables are correctly set
• Check token permissions match required scopes
• Ensure tokens haven’t expired

---

Schema Reference

mcp_servers:
  [server-name]:
    type?: "stdio" | "sse" | "http"  # Transport (inferred: http if url set, else stdio)
    command?: string      # Executable for process-based servers
    args?: string[]       # Command arguments
    env?: Record<string, string>  # Environment variables
    url?: string          # URL for HTTP/SSE-based servers
    headers?: Record<string, string>  # Request headers for sse/http servers
    timeout?: number      # Per-server tool-call timeout in ms (below 1000 ignored)
    alwaysLoad?: boolean  # Always include this server's tools in the prompt

Every field is passed through to the Agent SDK unchanged. A bare url with no type still becomes type: "http", so existing configs keep working.

---

Related Pages

• Agent Configuration — Full agent config reference
• plugins — Claude Code plugins, which can also supply MCP servers
• Permissions — Tool permission controls
• Environment Variables — Environment configuration