stella mcp
Manage MCP servers. Search for them, install one, list what's configured, and see usage stats.
MCP stands for Model Context Protocol. MCP servers give stella extra tools it can use during a session. stella connects to your configured servers when a session starts.
stella mcp is the command-line way to manage these servers. The Command Deck has an MCP tab (/mcp) that does the same job interactively. Use the MCP tab to turn a server on or off for a single session, or to enter a credential it needs.
See MCP servers for how MCP tools reach the agent.
Synopsis
stella mcp <list|search|install|remove|grant|login|logout|usage> [args]What it does
stella mcp reads and writes your workspace's .stella/mcp.toml file. It also talks to the MCP server registry over HTTP to search for servers and install them. It does not need a provider API key. Any server listed in .stella/mcp.toml connects at the start of each interactive session.
Subcommands
stella mcp list
List the MCP servers set up in .stella/mcp.toml. Each entry shows its name and description, saved when you installed it, with its local alias underneath. If a server is waiting for your approval, this list flags it. If a server was added by hand, or has no saved description, the list shows its endpoint instead: the URL or the command that starts it.
stella mcp listThe alias matters because it appears in tool names. Installing com.stripe/mcp writes [servers.mcp]. That alias, mcp, becomes part of the tool name, like mcp__mcp__create_refund. A list that only showed the alias wouldn't tell you which server is which, so stella shows the full name and description too.
stella mcp search <query>...
Search the MCP server registry. This uses the mcp.registry_url from settings.json if you set one, or the official registry if you didn't. Leave off the query to page through every server. Use --limit to control how many show per page.
stella mcp search filesystem
stella mcp search github --limit 5Each row shows three facts that tell you whether to trust a server: its source tier, its install count, and its signature status.
The source tier comes from the server's namespace:
official— published under the registry's own namespace.vendor— published under a domain the publisher proved they control, for examplecom.stripe/mcp.community— published from a code-hosting account, for exampleio.github.acme/…, or the registry's anonymous namespace.
Install count shows how many people installed the server, or "installs unknown" if the registry doesn't publish that number. stella never shows a fake 0.
"Signed" means the registry has confirmed who published the entry, and that entry is marked active. It does not mean stella checked a signature on the actual files — no MCP registry publishes one to check yet. Anything the registry can't attribute to a publisher, or has withdrawn, shows as "blocked." stella mcp install refuses to install a blocked server.
stella mcp install <name>
Install a server from the registry into .stella/mcp.toml, using the name shown by stella mcp search. This saves you from editing the file by hand. Use --alias to set a local name; by default, stella makes one from the server's name. Installing over an existing entry replaces it. MCP servers don't have versions.
stella mcp install filesystem
stella mcp install github --alias ghIf the registry can't vouch for a server, install refuses it. Installing writes the command stella will later run to start the server, so this check happens at install time, not just when you search.
A newly installed server starts out withheld. None of its tools are offered to the model, and any call to it is refused, until you review what it can do and approve it with stella mcp grant (see below). If you reinstall a server you already approved, it does not ask you again.
stella mcp remove <name>
Remove a server from .stella/mcp.toml by its local name.
stella mcp remove filesystemstella mcp grant <name>
Connect to a configured server, show what it says it can do, and record whether its tools may be used. This is the command-line version of the approval step in the MCP tab: pressing e on a server you haven't approved yet shows the same information and asks the same question.
stella mcp grant github # show what it can do, then ask
stella mcp grant github --yes # approve without asking
stella mcp grant github --revoke # take back an approval you gave beforeThis connects to the real server because what matters is what it announces right now, not what a registry listing said in the past. Unless you type an explicit y, the prompt treats everything else, including closed input, as no.
Your decision is saved as granted in .stella/mcp.toml, so it applies to every future session. Turning a server on or off is different — that's per-session only. There are three states, and each means something different:
In mcp.toml | Written by | The model can call it |
|---|---|---|
granted = true | a grant | yes |
granted = false | an install, or --revoke | no |
no granted key | you, editing the file | yes |
If you add a server by hand, with no granted key, stella treats it as approved. Writing the connection details yourself already counts as review. The approval step exists for the other case: installing a server from a search result with one keystroke, which adds a server you haven't reviewed. A server that comes from an installed plugin also has no granted key, for the same reason.
A withheld server still connects. That's how stella learns what it can do. But any call to it is refused, and the refusal names this command so you know what to run next.
stella mcp login <name> / stella mcp logout <name>
Log in (or out) with OAuth for a configured HTTP server that needs it. Tokens are saved to .stella/private/mcp_oauth.json and refresh automatically each time a session starts.
If a server rejects a connection with 401 Unauthorized, stella does not keep retrying it on every startup. It caches the 401 in .stella/private/mcp_auth_probes.json and skips that server for 15 minutes. During that time, it shows a single placeholder tool, mcp__<name>__login_required, telling the model, and you, to run stella mcp login <name>. Logging in clears this wait right away; otherwise stella tries again once the 15 minutes pass.
stella mcp login github
stella mcp logout githubstella mcp usage
Show how much each MCP tool has been used, from .stella/private/store.db: calls per server and per tool.
stella mcp usageTurning a server on or off for one session, and entering any credentials it needs, both happen in the deck's MCP tab (/mcp). Those settings apply only to that session, so they aren't part of this command. The MCP tab also has an inspector: press ctrl+o on a server to see its full details — description, registry entry, repository, endpoint, what it announced when stella connected, its credential fields, and every tool it offers with a call count. If a server has no saved description yet, press r inside the inspector to look one up in the registry.