MCP Servers

Connect Model Context Protocol servers to Stella so their tools merge into the agent at session start.

Stella can connect to Model Context Protocol (MCP) servers and merge their tools into the agent. This lets you extend the agent with capabilities that live outside your workspace — without writing a custom script tool for each one.

Configuration

MCP servers are configured in .stella/mcp.toml in your workspace. Stella connects to each configured server at session start and merges the tools it exposes into the agent, alongside the built-in tools and any custom tools.

The quickest way to add a server is the stella mcp command family — stella mcp search <query> to find one in the registry, then stella mcp install <name> to write the .stella/mcp.toml entry for you (no hand-editing). stella mcp list shows what's configured, and stella mcp remove <name> drops one.

Because the tools are added at session start, connecting a new server takes effect on your next session.

stella tools does not enumerate MCP tools — it prints a note that MCP servers merge more tools at session start. Confirm a server is wired up with stella mcp list, or verify its tools from inside a session (the deck's MCP tab, /mcp).

Example configuration

# .stella/mcp.toml

[servers.filesystem]
transport = "stdio"
cmd = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

[servers.github]
transport = "http"
url = "https://mcp.example.com/mcp"
headers = { Authorization = "Bearer …" }

A server entry needs a transport discriminant — stdio or http:

stdio — cmd is the executable and args its arguments; Stella launches the child process and speaks JSON-RPC over its stdio.
http — url is a streamable-HTTP endpoint Stella POSTs JSON-RPC to; the optional headers table holds static headers replayed on every request (an Authorization bearer, an API key). Header values are written to mcp.toml verbatim but redacted from logs and debug output.

Either way, Stella merges the tools the server reports for the session.

A stdio MCP subprocess runs with a scrubbed environment — ambient shell variables (including credentials like ANTHROPIC_API_KEY or GITHUB_TOKEN) are not inherited. Any variable the server needs must be listed explicitly in the entry's env table, e.g. env = { GITHUB_TOKEN = "…" }.

MCP tools are treated like any other tool once merged in: they follow the per-tool permission model and their calls can be gated or blocked with a PreToolUse hook.

Configuration

Example configuration

On this page