MCP Servers
MCP servers are tool servers declared by a SKILL.md file or the runtime catalog. The bot starts them when the corresponding skill becomes active, stops them when idle, and brings them back when something calls them.
What an MCP server is
MCP (Model Context Protocol) is a small standard for tool servers. A tool server is a separate program — for example, the official GitHub MCP server — that knows how to do one set of jobs (read repos, open issues, send Slack messages). When the bot loads it, it gets a handful of new tools for the job.
You do not run MCP servers yourself. Something declares the server — either a SKILL.md file or the runtime catalog under Settings → MCP — and the bot starts the server for you when the corresponding skill becomes active, then shuts it down when no one has used it for a while.
MCP is on by default
MCP works out of the box — you do not have to turn anything on. The toggle in Settings → MCP is a kill switch for disabling the feature entirely, not a prerequisite for using it.
What the bot does for you
When a skill with an MCP server becomes active, the bot runs the command, talks to the server over its standard input and output, performs the initialize and tools/list handshake, and wraps each reported tool as a normal tool the LLM can call for the rest of the chat.
If nothing calls those tools for a few minutes, the bot stops the server to free memory. The next call brings it back automatically — you do not have to do anything. The idle check runs roughly once a minute, so the idle timeout has ~60-second precision.
Two ways to declare an MCP server
There are two ways to tell the bot about an MCP server, and both end up in the same place — a skill that the bot can activate. Pick whichever is more convenient.
Inside a SKILL.md file
Write a SKILL.md file with an mcp: block in its YAML frontmatter. Use this when you want to bundle prompt instructions with the MCP server — a code-review skill that pulls from GitHub, a research skill that wraps a scraping server.
Option A
In the runtime catalog
Open Settings → MCP and add an entry to the catalog. Use this when you just want the tools with no extra instructions — the entry becomes a dynamic skill named mcp-<entry-name>, ready to activate like any other skill.
Option B
Option A — declaring MCP in a SKILL.md
Put an mcp: block in the skill frontmatter. See Skills for the full SKILL.md format.
---
name: github-assistant
description: Work with GitHub via MCP
mcp:
command: npx -y @modelcontextprotocol/server-github
env:
GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
startup_timeout: 30
idle_timeout: 10
---
Use the available MCP tools to work with GitHub.command
The shell command that starts the server. It runs inside the bot runtime, so the binary must exist there.
Required
env
Environment variables passed to the server. ${VAR} is filled in from the skill's vars: block first, then the OS environment.
Optional
startup_timeout
How many seconds to wait for the server to come up. Default 30. Raise it if your server does heavy setup work.
Optional
idle_timeout
How many minutes of no calls before the bot stops the server. Default 5. The next call starts it again.
Optional
Option B — adding a server to the runtime catalog
Open Settings → MCP. The first card sets the runtime defaults (Default Startup Timeout, Default Idle Timeout, and the Enable MCP kill switch). Below it is the catalog — a table of MCP servers with Add, Edit, and Delete buttons.
Each catalog entry becomes a dynamic skill named mcp-<entry-name>. You activate it the same way you activate any skill — describe what you want and let the bot call its skill_transition tool. Dynamic skills show up in the /skills list alongside hand-written ones.
name
Lowercase identifier. Must match [a-z0-9][a-z0-9_-]* — lowercase letters, digits, hyphens, and underscores, starting with a letter or digit. Becomes the suffix of the generated skill name, so choose a short, memorable word like github or filesystem.
Required
description
Optional short description. Shown in the marketplace and used as the skill's description. Defaults to "MCP server: <name>" when omitted.
Optional
command
The shell command that starts the server. Entries with a blank command are skipped when the bot materializes skills.
Required
env
Environment variables passed to the server. ${VAR} placeholders are resolved only from the OS environment — catalog entries have no per-skill vars block. Unresolved placeholders are left as-is.
Optional
startupTimeoutSeconds / idleTimeoutMinutes
Per-entry startup and idle timeouts. Default to 30 seconds and 5 minutes. Override the runtime defaults for this one entry.
Optional
enabled
Flag for individual disable without deleting the entry. Disabled entries are not materialized into skills, so they do not appear in /skills.
Default: true
env resolution differs between the two paths
SKILL.md files can define a vars: block in their frontmatter, and env placeholders resolve from those vars first before falling back to the OS environment. Catalog entries do not have vars — their envplaceholders go straight to the OS environment. Set tokens in the bot's environment variables if you use the catalog path.
Common problems
Server will not start
Check: the binary should exist in the bot runtime environment. Fix: install the binary where the bot runs, or change command to one that exists.
command not found
Handshake times out
Check: look for MCP startup lines in the bot logs. Fix: raise startup_timeout (SKILL.md) or startupTimeoutSeconds (catalog) — the server may need longer to come up.
startup timed out
Token errors inside the server
Check: confirm the variable is set where the bot reads from — skill vars for SKILL.md, OS environment for catalog entries. Fix: define the missing variable in the right place.
env not resolved
tools/list returns empty
Check: look for tools/list lines in the bot logs. Fix: update the server — its protocol version may be older than the one the bot expects.
protocol mismatch
What to do next
Related pages
User Guide
Skills
What a skill is, how to install one from the marketplace, and how to turn one on in a chat.
Cookbook
Connect GitHub via MCP
Create a skill that launches the GitHub MCP server, wire up authentication, and verify the bot transitions into it on a real request.
Reference
Troubleshooting
Symptom-driven lookup for common runtime problems. Each entry is strict: symptom, likely cause, check, fix.