Connections (MCP Servers)

MCP (Model Context Protocol) is a protocol that gives AI agents a standard way to reach external tools and services without each one needing a custom integration. In Headmaster, adding an MCP server instantly extends the agent’s capabilities.

AI Agent ←→ MCP Protocol ←→ External Tools / Services

Transport types

Transport	Use case	Config fields
`stdio`	Local CLI servers	`command` + `args` + `env`
`sse`	Remote servers (Server-Sent Events)	`url` + optional `headers`
`http`	Remote servers (plain HTTP)	`url` + optional `headers`
`streamable_http`	Remote servers (streamable HTTP)	`url` + optional `headers`

Common MCP servers

Server	What it does	Install
Filesystem	Give the agent access to a specific directory	`npx -y @modelcontextprotocol/server-filesystem /path`
GitHub	Read/write repos, issues, PRs	`npx -y @modelcontextprotocol/server-github`
Slack	Read and send messages	`npx -y @modelcontextprotocol/server-slack`
Browser	Control a headless browser	`npx -y @modelcontextprotocol/server-chrome-devtools`
Memory	Store important info and reminders	`npx -y @modelcontextprotocol/server-memory`
Git	Check commit history, branches, diffs	`npx -y @modelcontextprotocol/server-git`
Postgres	Query SQL databases	`npx -y @modelcontextprotocol/server-postgres`

See the full MCP Server List for more.

Adding an MCP server

By JSON config

Open MCP management

Go to Settings → Headmaster’s Library → Connections → MCP tab.

Click Add MCP Service → Add via JSON

Paste your server config.

Confirm

Headmaster validates the config and tests the connection automatically.

stdio (local CLI server) example:

{
  "mcpServers": {
    "filesystem": {
      "description": "Local filesystem access",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Remote (SSE / HTTP) example:

{
  "mcpServers": {
    "my-remote-server": {
      "description": "Remote MCP server",
      "type": "streamable_http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

By importing from a CLI agent

Click Add MCP Service → Import from CLI

Select which CLI agent to import from (Claude Code, Codex, Gemini CLI, Qwen Code, Cursor, etc.).

Review and save

Headmaster reads the CLI’s existing config and imports it directly.

This is the fastest path if you already have MCP servers configured in another CLI tool.

Shared across all specialists

When you add an MCP server, it’s available to all specialists automatically — add once, every specialist can use it. Headmaster also syncs enabled MCP servers to all detected CLI agents. If you have Claude Code and Codex both installed, enabling a server in Headmaster makes it available to both.

Managing your servers

Server status

Status	Meaning
✅ Connected	Running normally
❌ Connection failed	Unavailable — check config and network
🔄 Testing	Testing connection
⚪ Disconnected	Not started

Operations

Enable / Disable — toggle switch. Headmaster syncs enabled servers to all detected CLI agents.
Test connection — click the refresh button to re-test.
Edit — click edit, modify, and save (auto re-tests on save).
Delete — click delete, confirm. Automatically removes from all synced CLI tools.

Troubleshooting

Service connection failed

Possible causes: Incorrect path, missing dependencies, network issue, permissions.Solutions: Check command/args, run npm install -g for the server package, check network and permissions.

Empty tool list

Possible causes: Bad implementation, version mismatch, missing parameters.Solutions: Check the service implementation, update the server version, add missing env vars.

CLI sync failed

Possible causes: Old CLI version, format mismatch, bad CLI installation.Solutions: Update the CLI, disable/re-enable the service, verify CLI installation.

stdio server won't start

Possible causes: Command not found, missing environment variables.Solutions: Verify the command runs in a terminal first, check env keys in your config.

Remote server timeout

Possible causes: Network, firewall, wrong URL.Solutions: Test with curl -I <url>, check firewall rules, verify the URL is correct.

Tools & Toolsets

The 60+ built-in tools and how to configure them per specialist.

Your Crew

How MCP servers sync to external CLI agents.

Getting Started

Core Concepts

HeadmasterUI Settings

Runtime Settings

Features

Security & Privacy

Maintenance

Reference

Connections (MCP Servers)

Connections (MCP Servers)

Transport types

Common MCP servers

Adding an MCP server

By JSON config

By importing from a CLI agent

Shared across all specialists

Managing your servers

Server status

Operations

Troubleshooting

Tools & Toolsets

Your Crew

​Connections (MCP Servers)

​Transport types

​Common MCP servers

​Adding an MCP server

​By JSON config

​By importing from a CLI agent

​Shared across all specialists

​Managing your servers

​Server status

​Operations

​Troubleshooting

Tools & Toolsets

Your Crew

Connections (MCP Servers)

Transport types

Common MCP servers

Adding an MCP server

By JSON config

By importing from a CLI agent

Shared across all specialists

Managing your servers

Server status

Operations

Troubleshooting