Skip to main content

​
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

TransportUse caseConfig fields
stdioLocal CLI serverscommand + args + env
sseRemote servers (Server-Sent Events)url + optional headers
httpRemote servers (plain HTTP)url + optional headers
streamable_httpRemote 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

  1. Open Headmaster.
  2. Click Settings in the left sidebar.
  3. 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

ServerWhat it doesInstall
FilesystemGives the agent access to a specific directorynpx -y @modelcontextprotocol/server-filesystem /path
GitHubRead and write repos, issues, PRsnpx -y @modelcontextprotocol/server-github (needs GITHUB_TOKEN)
SlackRead and send messagesnpx -y @modelcontextprotocol/server-slack (needs SLACK_TOKEN)
BrowserControl a headless browsernpx -y @modelcontextprotocol/server-chrome-devtools
MemoryStore important info and remindersnpx -y @modelcontextprotocol/server-memory
GitCheck commit history, branches, diffsnpx -y @modelcontextprotocol/server-git
PostgresQuery SQL databasesnpx -y @modelcontextprotocol/server-postgres (needs connection string)
CustomAny MCP-compliant server you write or installFollow the MCP spec
See the full MCP Server List for more.

​
Managing your servers

​
What each status means

StatusMeaning
✅ ConnectedRunning normally
❌ Connection failedUnavailable — check config and network
🔄 TestingTesting connection
⚪ DisconnectedNot 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

IssuePossible causesSolutions
Service connection failedIncorrect path, missing deps, network, permissionsCheck command/args, run npm install -g, check network and permissions
Empty tool listBad implementation, version mismatch, missing paramsCheck service implementation, update version, add missing env vars
CLI sync failedOld CLI version, format mismatch, bad installationUpdate CLI, disable/re-enable service, verify CLI installation
stdio server won’t startCommand not found, missing env varsVerify the command runs in a terminal first, check env keys
Remote server timeoutNetwork, firewall, wrong URLTest with curl -I <url>, check firewall rules, verify URL

​
Going further