MCP servers
Connect Theus to external tools and data sources through the Model Context Protocol (MCP): add servers over stdio, SSE or HTTP, scope them per project or per user, and manage them from the CLI or the /mcp panel.
What MCP gives you
An MCP server exposes tools, slash commands and resources that Theus can use during a session. Once a server is connected, its tools appear alongside the built-in ones and its commands show up in the session. Theus supports three transports:
- stdio — a local subprocess Theus launches and talks to over standard input/output. This is the default when you don't specify a transport.
- sse — a remote server reached over Server-Sent Events at a URL.
- http — a remote server reached over streamable HTTP at a URL.
Configure MCP servers
The main entry point is theus mcp add. The general shape is:
theus mcp add <name> <commandOrUrl> [args...]Add a stdio server
Everything after -- becomes the subprocess command and its arguments. Pass environment variables with -e KEY=value (repeatable):
# Local server launched as a subprocess
theus mcp add my-server -- npx my-mcp-server
# With environment variables
theus mcp add -e API_KEY=xxx my-server -- npx my-mcp-server
# With subprocess flags
theus mcp add my-server -- my-command --some-flag arg1Add a remote HTTP or SSE server
Use --transport http or --transport sse and pass a URL. Add headers with -H / --header (repeatable):
# HTTP server
theus mcp add --transport http sentry https://mcp.sentry.dev/mcp
# HTTP server with a header
theus mcp add --transport http corridor https://app.corridor.dev/api/mcp \
--header "Authorization: Bearer ..."--transport, Theus interprets it as a stdio command and warns you. Always set --transport http or --transport sse for remote servers.Options for theus mcp add
| Option | Description |
|---|---|
-s, --scope <scope> | Configuration scope: local, user or project. Defaults to local. |
-t, --transport <transport> | Transport type: stdio, sse or http. Defaults to stdio. |
-e, --env <env...> | Set environment variables for a stdio server (e.g. -e KEY=value). |
-H, --header <header...> | Set request headers for HTTP/SSE servers (e.g. -H "X-Api-Key: abc123"). |
--client-id <clientId> | OAuth client ID for HTTP/SSE servers. |
--client-secret | Prompt for the OAuth client secret (or read it from the MCP_CLIENT_SECRET environment variable). |
--callback-port <port> | Fixed port for the OAuth callback, for servers that require pre-registered redirect URIs. |
--client-id, --client-secret and --callback-port apply only to HTTP/SSE transports; they are ignored (with a warning) for stdio.
Configuration scopes
The --scope option decides where the server definition is written and who can see it:
| Scope | Meaning | Stored in |
|---|---|---|
local | Private to you in the current project (the default). | Your global Theus config, keyed to this project. |
project | Shared with everyone who works in the project. | .mcp.json at the project root. |
user | Available across all of your projects. | Your global Theus config under ~/.theus/. |
.mcp.json come from the repository, not from you. Theus asks you to approve project-scoped servers before it will spawn them. Use theus mcp reset-project-choices to clear your approvals and rejections for this project.Manage servers from the CLI
| Command | What it does |
|---|---|
theus mcp list | List configured MCP servers and their health. |
theus mcp get <name> | Show details about a single server. |
theus mcp add <name> <commandOrUrl> [args...] | Add a server (stdio, SSE or HTTP). |
theus mcp add-json <name> <json> | Add a server from a JSON string. |
theus mcp remove <name> | Remove a server. Without --scope, removes it from whichever scope it exists in. |
theus mcp add-from-theus-desktop | Import MCP servers from Theus Desktop (macOS and WSL only). |
theus mcp reset-project-choices | Reset approvals and rejections for project-scoped (.mcp.json) servers in this project. |
theus mcp serve | Start the Theus MCP server (exposes Theus itself as an MCP server). |
theus mcp list and theus mcp get skip the workspace-trust dialog and spawn stdio servers from .mcp.json for health checks. Only run them in directories you trust.Manage servers inside a session
The /mcp slash command opens the MCP panel, where you can review connected servers, their tools and their status. It also accepts arguments:
/mcp enable [server-name]— enable a specific server, or all servers if you omit the name./mcp disable [server-name]— disable a specific server, or all of them./mcp reconnect <server-name>— reconnect a server without restarting Theus.
Load servers ad hoc
You can point a single run at extra MCP configuration without saving it:
--mcp-config <configs...>— load MCP servers from one or more JSON files or JSON strings (space-separated).--strict-mcp-config— use only the servers from--mcp-configand ignore every other MCP configuration.
theus --mcp-config ./servers.json --strict-mcp-configAuthentication
For HTTP and SSE servers that use OAuth, provide --client-id and, when needed, --client-secret. The secret can be typed at the prompt or supplied via the MCP_CLIENT_SECRET environment variable. If the server requires a fixed redirect URI, set --callback-port so the OAuth callback lands on a known port.