> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcaplabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections (MCP servers)

> - [MCP Specification](https://modelcontextprotocol.io/) - [MCP Server List](https://github.com/modelcontextprotocol/serv

# Connections (MCP servers)

Connections in Headmaster's Library covers two things: **model providers** (covered in [Models & providers](models-providers.md)) 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.

```text theme={null}
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

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](https://modelcontextprotocol.io/)                  |

See the full [MCP Server List](https://github.com/modelcontextprotocol/servers) 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](https://modelcontextprotocol.io/)
* [MCP Server List](https://github.com/modelcontextprotocol/servers)
* [Getting started](getting-started.md)
* [Your Crew](your-crew.md) — how MCP syncs to external CLI agents