Skip to main content
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

FieldTypeDescription
namestring (required)Display name and tool namespace prefix
transport”stdio” | “http” | “sse”Transport type (default: “stdio”)
commandstringCommand to spawn (stdio transport)
argsstring[]Arguments for command
envRecord<string,string>Environment variables for subprocess
urlstringURL for http/sse transports
timeoutnumberPer-tool-call timeout in ms (default: 30000)
disabledbooleanDisable without removing config
headersRecord<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”.
ShortcutAction
TypeFilter servers by name
Ctrl+AAdd new server
Ctrl+DDelete selected server
Ctrl+TToggle enable/disable
Ctrl+EEdit server config
Ctrl+RRetry failed connection
TabSwitch to tools browser
EnterOpen 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"