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

# MCP Servers

> Connect to Model Context Protocol servers for external tool integration. Supports stdio, HTTP, and SSE transports.

SoulForge connects to MCP servers, exposing their tools alongside built-in tools. Three transports are supported: **stdio** (local subprocess), **Streamable HTTP** (remote), and **SSE** (legacy remote).

## Quick start

Add a simple stdio server to your config:

```json theme={null}
{
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  ]
}
```

Tools from this server are now available as `mcp__github__<tool>`.

## Configuration

Add `mcpServers` to your global config (`~/.soulforge/config.json`) or project config (`.soulforge/config.json`). Project config overrides global by server name.

```json theme={null}
{
  "mcpServers": [
    {
      "name": "github",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." },
      "timeout": 30000
    },
    {
      "name": "sentry",
      "transport": "http",
      "url": "https://mcp.sentry.dev/sse",
      "headers": { "Authorization": "Bearer ..." },
      "timeout": 30000
    },
    {
      "name": "legacy-service",
      "transport": "sse",
      "url": "https://legacy.example.com/events",
      "headers": { "X-API-Key": "..." },
      "disabled": false
    }
  ]
}
```

## Config reference

| Field       | Type                       | Description                                  |
| ----------- | -------------------------- | -------------------------------------------- |
| `name`      | string (required)          | Display name and tool namespace prefix       |
| `transport` | "stdio" \| "http" \| "sse" | Transport type (default: "stdio")            |
| `command`   | string                     | Command to spawn (stdio transport)           |
| `args`      | string\[]                  | Arguments for command                        |
| `env`       | `Record<string,string>`    | Environment variables for subprocess         |
| `url`       | string                     | URL for http/sse transports                  |
| `timeout`   | number                     | Per-tool-call timeout in ms (default: 30000) |
| `disabled`  | boolean                    | Disable without removing config              |
| `headers`   | `Record<string,string>`    | HTTP headers for http/sse transports         |

## Tool namespacing

MCP tools are namespaced as `mcp__<server>__<tool>` to prevent collisions with built-in tools. A server named "github" with tool "create\_issue" becomes `mcp__github__create_issue`.

## Transport types

**stdio** — Spawns a local subprocess. The server communicates via JSON-RPC over stdin/stdout. Best for local tools and development.

**http** — Streamable HTTP (recommended for remote servers). Modern MCP transport with efficient streaming.

**sse** — Server-Sent Events. Legacy remote transport. Use http for new servers.

## Lifecycle

* **Startup**: All enabled servers connect with bounded concurrency (max 5 simultaneous)
* **Retry**: Failed servers retry up to 3 times with exponential backoff (1s, 2s, 4s)
* **Auto-restart**: Servers that crash automatically restart (stdio transport only)
* **Cleanup**: On exit, all connections are closed and subprocesses terminated

## TUI shortcuts

Open the MCP manager with `/mcp` or `Ctrl+K` → search "mcp".

| Shortcut | Action                  |
| -------- | ----------------------- |
| Type     | Filter servers by name  |
| `Ctrl+A` | Add new server          |
| `Ctrl+D` | Delete selected server  |
| `Ctrl+T` | Toggle enable/disable   |
| `Ctrl+E` | Edit server config      |
| `Ctrl+R` | Retry failed connection |
| `Tab`    | Switch to tools browser |
| `Enter`  | Open server detail view |

## Headless mode

MCP servers connect automatically in headless mode. Tools are available to the agent immediately:

```bash theme={null}
soulforge --headless "use the github MCP to list open issues"
```