MCP Servers

Agent Harbor supports the Model Context Protocol (MCP) to extend agents with external tools and capabilities. MCP servers enable agents to interact with external services, databases, APIs, and custom tools.

Usage

Pass an MCP configuration file when starting an agent:


ah agent start --agent claude --mcp-config ~/.config/mcp-servers.json --prompt "Your task"

The --mcp-config flag supports tilde expansion for home directory paths.

Configuration File Format

Create a JSON file with your MCP server definitions:


{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "weather-api": {
      "url": "https://mcp.example.com/weather",
      "headers": {
        "Authorization": "Bearer ${WEATHER_API_KEY}"
      },
      "timeout": 30000
    }
  }
}

Transport Types

MCP servers support three transport mechanisms:

STDIO Transport

For local processes (Node.js servers, Docker containers, local binaries):


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

Field	Required	Description
`command`	Yes	Executable command
`args`	No	Command arguments array
`env`	No	Environment variables (supports `${VAR}` resolution)

HTTP Transport

For remote REST API servers:


{
  "mcpServers": {
    "my-api": {
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      },
      "timeout": 60000
    }
  }
}

Field	Required	Description
`url`	Yes	Server URL
`headers`	No	HTTP headers (supports `${VAR}` resolution)
`timeout`	No	Request timeout in milliseconds

SSE Transport

For Server-Sent Events streaming:


{
  "mcpServers": {
    "events": {
      "url": "https://mcp.example.com/events"
    }
  }
}

Uses the same fields as HTTP transport.

Common Configuration Fields

Field	Description
`enabled_tools`	Array of tool names to enable (allowlist)
`disabled_tools`	Array of tool names to disable (denylist)
`timeout`	Request timeout in milliseconds

Environment Variable Resolution

Agent Harbor resolves ${VAR_NAME} references in configuration:


{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Variables are resolved from your shell environment before the agent launches. This keeps secrets out of configuration files.

Agent-Specific Behavior

Each agent type handles MCP configuration differently:

Claude Code

Writes mcp-config.json to agent’s home directory
Supports all transports (stdio, http, sse)
Supports enabled_tools and disabled_tools


ah agent start --agent claude --mcp-config ~/.config/mcp-servers.json

Codex

Generates TOML config in isolated .codex directory
Sets CODEX_CONFIG_DIR environment variable
STDIO and HTTP transport (SSE treated as HTTP)
Uses env_vars array for environment variables
HTTP servers use bearer_token_env_var for authentication

Internal TOML format example:


[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env_vars = ["GITHUB_TOKEN"]
tool_timeout_sec = 30
enabled_tools = ["create_issue", "list_repos"]

Gemini

Appends to existing ~/.gemini/settings.json
All transports supported
Uses httpUrl instead of url for HTTP transport
Servers activated via --allowed-mcp-server-names flag


ah agent start --agent gemini --mcp-config ~/.config/mcp-servers.json
# Internally: gemini --allowed-mcp-server-names github,weather-api

GitHub Copilot CLI

Writes mcp-config.json to agent’s home directory
All transports supported
Automatically defaults tools to ["*"] (all tools)
Uses @ prefix for file paths internally


ah agent start --agent copilot --mcp-config ~/.config/mcp-servers.json
# Internally: copilot --additional-mcp-config @/path/to/mcp-config.json

Security

Never hardcode secrets in configuration files. Always use ${VAR_NAME} references.

File Permissions: Set appropriate permissions on config files: chmod 600 mcp-config.json
Network Isolation: When using HTTP/SSE servers in sandbox mode, use --allow-network true
Credential Rotation: Regularly rotate tokens and API keys

Error Handling

Missing ${VAR_NAME} references produce clear error messages
Invalid transport configurations are caught during validation
MCP server connectivity failures are logged with diagnostic information

Examples

GitHub Integration


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


export GITHUB_TOKEN="ghp_your_token_here"
ah agent start --agent claude --mcp-config mcp-config.json --prompt "Create an issue"

Database Access


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

Multiple Servers


{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": { "SLACK_TOKEN": "${SLACK_TOKEN}" }
    },
    "internal-api": {
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${INTERNAL_API_KEY}" }
    }
  }
}