Connections (MCP servers)

Connections in Headmaster's Library covers two things: model providers (covered in Models & providers) and MCP servers — external tools the agent can call on during a conversation.

Understanding MCP

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, it enables extending agent functionality, unified management, simplified configuration, and real-time monitoring.

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

MCP sits between the agent and your external services — it handles discovery, calling, and result passing so the agent doesn't need to know each service's API directly.

Built-in capabilities

Unified management interface: Centralized management in settings.
Multiple addition methods: JSON configuration and one-click import from CLI agents.
Automatic connection testing: Validates availability after addition.
Batch operations: One-click enable/disable.
Status monitoring: Real-time display of connection status and tools.

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 |

Getting going

Before you start

Headmaster installed and running.
At least one AI model configured.
Basic JSON knowledge (optional — the UI handles most of it).

Accessing MCP management

Open Headmaster.
Click Settings in the left sidebar.
Open Headmaster's Library → Connections → MCP tab.

Adding an MCP server

Adding a server by JSON config

Follows the standard mcpServers schema.

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 / streamable_http) example:

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

Steps: Click Add MCP Service → Add via JSON → paste config → confirm → automatic testing occurs.

Importing from a CLI agent

Import existing MCP configs from detected CLI agents (Claude Code, Codex, Gemini CLI, Qwen Code, Cursor, etc.).

Steps: Click Add MCP Service → Import from CLI → select CLI agent → click Import from CLI → review & save.

This is the fastest path if you already have MCP servers configured in another CLI tool — Headmaster reads their config and imports it directly.

Shared across all specialists

When you add an MCP server, it's available to all specialists automatically. You don't need to configure it per-specialist or per-conversation. This is the shared MCP model — 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.

Common MCP servers

| Server | What it does | Install | |---|---|---| | Filesystem | Gives the agent access to a specific directory | npx -y @modelcontextprotocol/server-filesystem /path | | GitHub | Read and write repos, issues, PRs | npx -y @modelcontextprotocol/server-github (needs GITHUB_TOKEN) | | Slack | Read and send messages | npx -y @modelcontextprotocol/server-slack (needs SLACK_TOKEN) | | 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 (needs connection string) | | Custom | Any MCP-compliant server you write or install | Follow the MCP spec |

See the full MCP Server List for more.

Managing your servers

What each status means

| 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.

Usage examples

File management: Organize desktop files via the filesystem MCP.
Browser automation: Open sites and search via the chrome-devtools MCP.
Git operations: Check commit history via the git MCP.
Memory management: Store important info and reminders via the memory MCP.
Database queries: Ask questions in plain English and get SQL results via the postgres MCP.

Troubleshooting

| Issue | Possible causes | Solutions | |---|---|---| | Service connection failed | Incorrect path, missing deps, network, permissions | Check command/args, run npm install -g, check network and permissions | | Empty tool list | Bad implementation, version mismatch, missing params | Check service implementation, update version, add missing env vars | | CLI sync failed | Old CLI version, format mismatch, bad installation | Update CLI, disable/re-enable service, verify CLI installation | | stdio server won't start | Command not found, missing env vars | Verify the command runs in a terminal first, check env keys | | Remote server timeout | Network, firewall, wrong URL | Test with curl -I <url>, check firewall rules, verify URL |

Going further

MCP Specification
MCP Server List
Getting started
Your Crew — how MCP syncs to external CLI agents

Connections (MCP)