MCP Servers

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:

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

{
  "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:

soulforge --headless "use the github MCP to list open issues"

Get started

Sponsors

Recipes

Providers

Tools

How it works

Reference

Quick start

Configuration

Config reference

Tool namespacing

Transport types

Lifecycle

TUI shortcuts

Headless mode

​Quick start

​Configuration

​Config reference

​Tool namespacing

​Transport types

​Lifecycle

​TUI shortcuts

​Headless mode

Quick start

Configuration

Config reference

Tool namespacing

Transport types

Lifecycle

TUI shortcuts

Headless mode