4 min read·Updated 2026-04-10

MCP Servers

The runtime supervises MCP servers declared in skill frontmatter: handshake, tool registration, idle timeout, and restart.

Mental model

Requires

MCP must be enabled in preferences/mcp.json. Skills without an mcp: block work without this flag.

MCP (Model Context Protocol) is a stdio-based handshake for external tool servers. A skill declares an MCP server in its frontmatter. When the skill activates, the runtime starts the server as a subprocess, performs initialize and tools/list, wraps each discovered tool as a native tool, and exposes it to the agent for the duration of the skill.

The reader should picture the runtime as an MCP supervisor: it owns the process lifetime, the handshake, idle timeout, and restart. The skill only declares what to run; the runtime decides when.

Lifecycle

An MCP server moves through five states. The runtime drives every transition; the agent cannot start or stop a server directly.

Declared — present in SKILL.md but the skill is not active. No process exists.
Starting — skill activation triggered the server. Subprocess spawned, stdio piped, awaiting initialize response. Bounded by startup_timeout.
Ready — handshake complete, tools/list returned, tools registered as native. Calls flow through the runtime wrapper.
Idle — no calls for idle_timeout minutes. Server remains running but eligible for teardown.
Stopped — subprocess killed after idle expiry or on skill deactivation. Next tool call transitions the server back to Starting.

Declaring an MCP server

preferences/mcp.json — global flag

json

{
  "mcp": {
    "enabled": true,
    "defaultStartupTimeout": 30,
    "defaultIdleTimeout": 5
  }
}

Declare the server in a skill's frontmatter. See Skills for the full SKILL.md contract.

command

Shell command to start the MCP server. Runs inside the runtime container; required binaries must exist there.

Required

env

Environment variables. ${VAR} is resolved from skill variables first, then OS environment.

Optional

startup_timeout

Seconds to wait for the initialize response. Default: 30. Increase for servers that do heavy setup.

Optional

idle_timeout

Minutes of inactivity before the runtime stops the server. Default: 5. Next tool call restarts it.

Optional

Troubleshooting

Server won't start

Check: docker exec golemcore-bot which <binary>. Fix: install the binary in the container, or change command to one that exists.

command not found

Handshake times out

Check: docker logs golemcore-bot | grep MCP. Fix: raise startup_timeout in skill frontmatter; the server may need longer to initialize.

initialize timeout

Token errors inside the server

Check: echo in the skill to verify skill variables or OS env contains the token. Fix: export the variable in the container environment or set it in skill variables.

env not resolved

tools/list returns empty

Check: docker logs golemcore-bot | grep 'tools/list'. Fix: ensure the server implements the MCP spec version the runtime expects; update the server.

protocol mismatch

What to do next

Connect GitHub via MCP

Step-by-step recipe that ties a skill to the GitHub MCP server, including token setup and verification.

Cookbook

Skills

Understand skills as the hosting context that drives MCP server lifecycles.

Concept

User Guide

Skills

What a skill is, how sticky activation works, and the SKILL.md contract. For concrete recipes, see the Cookbook.

Cookbook

Connect GitHub via MCP

Create a skill that launches the GitHub MCP server, wire up authentication, activate, and verify with a test query.

Reference

Troubleshooting

Symptom-driven lookup for common runtime problems. Each entry is strict: symptom, likely cause, check, fix.