Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

docs: supported MCP servers

Samrat Talukdarb8c0e2a83c9c
diff --git a/README.md b/README.md
index 5fcd3125..76ee16e9 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,8 @@ account is connected.
| Feature | Description | Docs |
| --- | --- | --- |
| Models and effort | Choose a model and an effort level (low, high, xhigh, max) per chat, from the models in your omnirush.ai account. Your own provider keys are not supported. | |
-| Skills | Add skills from the Library in Settings. Every model sees the same skills. MCP servers are turned off. | |
+| Skills | Add skills from the Library in Settings. Every model sees the same skills. | |
+| MCP servers | Local MCP servers from the account's supported list, such as filesystem, git, SQLite, memory, sequential thinking, time, and Playwright on local pages. Remote and account-linked servers are not supported. Configure them in Settings > MCP. | [skills-and-mcp.md](docs/skills-and-mcp.md) |
| Git workflows | The agent clones, branches, creates worktrees, commits, pushes, and opens and reviews pull requests with `gh`. Write commands ask once per session; destructive ones always ask. | [git-workflows.md](docs/git-workflows.md) |
| Approvals | The composer's full-permissions toggle switches between asking and allowing every tool call. | [approvals.md](docs/approvals.md) |
diff --git a/docs/skills-and-mcp.md b/docs/skills-and-mcp.md
index 2e7296e8..5a519848 100644
--- a/docs/skills-and-mcp.md
+++ b/docs/skills-and-mcp.md
@@ -70,7 +70,7 @@ You can also drop a `SKILL.md` folder into `.opencode/skills/` by hand; the serv
Skills are files, not config. The engine reads them from disk when it builds its project instance:
-- The engine-visible config file (`runtime-opencode-config.json` in the server state directory, passed as `OPENCODE_CONFIG`) does not contain skills. It contains the omnirush.ai provider block, the plugins, the `omnirush` agent definition (which denies the engine's own `customize-opencode` and creator skills) and the global MCP entries.
+- The engine-visible config file (`runtime-opencode-config.json` in the server state directory, passed as `OPENCODE_CONFIG`) does not contain skills. It contains the omnirush.ai provider block, the plugins, the `omnirush` agent definition (which denies the engine's own `customize-opencode` and creator skills).
- The engine scans the skill directories when it creates the instance for the workspace directory. `GET /skill` on the engine (proxied by the server for the v2 preview as `/api/skill`) returns the catalog with `name`, `description`, `location` and `content`.
- The catalog is cached for the life of the instance. A new, changed or removed skill becomes visible after the instance is rebuilt (`POST /instance/dispose` on the engine), which the app calls the engine reload.
@@ -78,44 +78,42 @@ The server's list (`GET /workspace/:id/skills?includeGlobal=true`) reads the sam
## MCP servers
-### Kinds of MCP entries
+MCP servers follow the account's list of supported servers: local servers that work on the project's own files and can be started again the same way, so a session that used them can be repeated. Examples on the default list: filesystem, git, SQLite, memory, sequential thinking, time, and Playwright on local pages. Remote and account-linked servers (Notion, Linear, GitHub, Slack, omnirush.ai Connect, managed OAuth sign-ins, MCP apps) are not supported: their answers come from an outside service or account.
-| Kind | Config | How it is added |
-| --- | --- | --- |
-| Local (stdio) | `{"type":"local","command":["node","/path/server.mjs"],"environment":{...},"enabled":true}` | Library, Add, MCP server (local), or Advanced, Add MCP. |
-| Remote (HTTP) | `{"type":"remote","url":"https://...","headers":{...},"enabled":true}` | Library, Add, MCP server (remote). |
-| Managed OAuth | remote URL plus OAuth settings | Library, Add, MCP server with Sign in; the server runs the OAuth flow and keeps the tokens in an encrypted vault. |
-| omnirush.ai Connect | `omnirush-cloud` and `omnirush-connect-*` | Provisioned by the account; not user-editable. |
+### The list
-MCP names must be alphanumeric with `-` or `_` and must not start with `-`. The names `omnirush-cloud`, `omnirush-connect-*` and `omnirush-direct-*` are reserved.
+- The backend sends the list in `GET /omnirush/collect/capabilities` as `mcp: {enabled, allow, deny, message}`. The server remembers the last one it saw in `<server state>/mcp/policy.json` (read at every start and refreshed while the app runs; a failed read keeps the last one; an answer without the block, or none ever seen, is MCP off).
+- `apps/server/src/mcp-allow/mcp-allow.mjs` applies it. The same file ships in the OmniRush CLI (`src/mcp/`); `PARITY.sha256` lists both copies.
+- An entry is allowed only when it starts a package on the list through `npx`/`bunx`/`pnpm dlx`/`yarn dlx`/`npm exec` (npm) or `uvx`/`uv tool run` (PyPI), at a version in the entry's range (left out: the entry's pinned version), and every file or folder it works on is inside the project. Allowed servers are renamed to the entry's id, so their tools are always `<id>_<tool>`.
### Adding an MCP server in the desktop app
-1. Open Settings, then Library. Click Add and choose MCP server (or open Advanced and click Add MCP).
-2. Enter a name, pick Remote or Local, and enter the URL or the command line. For a local server the command is split on whitespace into the `command` array.
-3. The app sends `POST /workspace/:id/mcp` with `{ name, config }`. The server validates the config, stores it in the workspace row of the runtime DB (`runtime_opencode_configs`, SQLite in the server state directory), and immediately registers it with the running engine (`POST /mcp` on the engine). It then records an audit entry and emits an `mcp` reload event.
-4. The card shows the engine status: Ready (connected), Needs sign-in, Paused (disabled), Offline or an error. Toggle the card to pause or resume the server; the toggle sends `POST /workspace/:id/mcp/:name/enabled` and the engine re-registers the entry.
+1. Open Settings, then MCP. The supported servers are listed with what they do and the command each adds (for example `npx -y @modelcontextprotocol/server-filesystem .` or `npx -y mcp-server-sqlite-npx data.db`). Click Add; or use Add, MCP server, with your own command line.
+2. The app sends `POST /workspace/:id/mcp` with `{ name, config }`. The server checks the entry against the list and refuses it with the reason when it is not supported; otherwise it stores it in the workspace row of the runtime DB and in `<server state>/mcp/workspaces/<project>.json` for the engine, records an audit entry and emits an `mcp` reload event (the app reloads the project's engine).
+3. Each configured server shows On (its package and version, and "runs in the sandbox" when the project's Linux sandbox is on) or Blocked with the reason.
-To remove a server, open its card and choose Remove. The server deletes the runtime row (`DELETE /workspace/:id/mcp/:name`) and tells the engine to drop the registration.
+To remove a server added in the app, choose Remove (`DELETE /workspace/:id/mcp/:name`).
### Where MCP config lives
-- Workspace MCP servers added from the app: the workspace row of the runtime DB. They are never written into the user's `opencode.json`.
-- Account-level entries (`omnirush-cloud`): the engine-global row of the runtime DB; these are the only MCP entries rendered into the engine-visible config file.
-- Static entries from `<workspace>/.opencode/opencode.json` or `~/.config/opencode/opencode.json`: read by the engine directly and listed in the app as project or global config entries (read-only from the app).
+- Servers added in the app: the workspace row of the runtime DB. They are never written into the project's `opencode.json`.
+- Entries in `<workspace>/opencode.json`, `<workspace>/.opencode/opencode.json` or `~/.config/opencode/opencode.json`: read by the engine directly; the list applies to them too. The app lists them as project or global entries (read-only).
+- The engine-global row never stores MCP entries; the engine-visible config file has no `mcp` key.
### How MCP servers reach the engine
-- On startup and after every engine reload, the server pushes each workspace's runtime MCP entries to the engine (`POST /mcp` with `{ name, config }`), one entry at a time so one dead server cannot block the rest. Failures are retried in the background and surfaced as `engineSync` on `GET /workspace/:id/mcp`.
-- The engine spawns local servers (stdio) or opens the HTTP transport, completes the MCP handshake (`initialize`, `notifications/initialized`) and calls `tools/list`. Its status is visible on `GET /mcp` on the engine and as the card status in the app.
-- MCP tools are exposed to the model as `<server>_<tool>` at prompt time. They do not appear in the engine's `/experimental/tool/ids` list, which only covers built-in and plugin tools; the connected status plus the server's `tools/list` call is the confirmation that the tools are available.
+- The server gives the engine `OMNIRUSH_MCP_POLICY_FILE`, `OMNIRUSH_MCP_REPORT_DIR` and `OMNIRUSH_MCP_WORKSPACE_DIR`. The engine plugin `omnirush-mcp-policy` (always loaded, last in the plugin list) adds the project's app-added servers to its config, then replaces `mcp` with the allowed servers only, keyed by id, pinned, paths checked, and run through the sandbox shell when the project's sandbox is on. It writes a report per project (`<server state>/mcp/reports/`) with one decision per entry; `GET /workspace/:id/mcp` returns it.
+- Nothing is pushed into a running engine: an added server starts when the project's engine instance reloads. The engine's own routes that would add a server at runtime or run its OAuth flow are refused; listing and connect/disconnect pass.
+- Playwright opens pages on this machine only (localhost); other pages are refused before the tool runs.
+- MCP tools reach the model as `<id>_<tool>` and are asked about like other tools (no allow rules are added for them).
+- The preview engine (v2) cannot apply the list: MCP stays off there (its servers are removed before each request, and a prompt in a project with MCP servers is refused with a message).
+- Uploads: a session in a project with at least one server on gets `environment.mcp_servers: [{id, package, version, runtime, sandbox}]`; other sessions upload exactly as before.
### Coexistence with the omnirush.ai provider
The engine-visible config file is rendered from the engine-global runtime row plus static built-ins:
- `provider.omnirush` (the omnirush.ai models, `baseURL` pointing at the local gateway broker) is added after any runtime `provider` entries, so a runtime provider with the same id cannot shadow it.
-- `mcp` holds only the engine-global entries (for example `omnirush-cloud`); workspace MCP entries are pushed dynamically and never collide with it.
- `disabled_providers` is copied through untouched.
- `model` defaults to the account catalog's default model (`omnirush/gpt-6-astra`) when the account is signed in. The `omnirush` provider's models come from the catalog the server syncs from `GET /omnirush/v1/models` (ids, names, efforts, limits and input types only); its package, base URL and credentials never do.
@@ -125,8 +123,8 @@ Adding skills or MCP servers never modifies the provider block.
The flows above were exercised against the bundled sidecar (`opencode` 1.18.18, `opencode serve`) in an isolated `HOME` with the server started through the embedded API and a loopback stub as the gateway:
-- `POST /workspace/:id/skills` wrote `.opencode/skills/release-notes/SKILL.md`; `GET /workspace/:id/skills` and `GET /workspace/:id/skills/release-notes` returned it with the trigger extracted from the "When to use" section. After an engine instance rebuild, the engine's `GET /skill` listed it with the exact body; the generated config file kept `provider.omnirush`, `model`, the 11 plugins and `mcp: {}` unchanged.
-- `POST /workspace/:id/mcp` with a local stdio fixture (`node mcp-stdio-fixture.mjs`) produced `engineSync.status: "ok"`, the engine reported `{"fixture-stdio":{"status":"connected"}}`, and the fixture logged `initialize`, `notifications/initialized` and `tools/list` from the engine. Disabling switched the engine status to `disabled`; enabling reconnected and re-listed tools; deleting removed the entry from the engine.
+- `POST /workspace/:id/skills` wrote `.opencode/skills/release-notes/SKILL.md`; `GET /workspace/:id/skills` and `GET /workspace/:id/skills/release-notes` returned it with the trigger extracted from the "When to use" section. After an engine instance rebuild, the engine's `GET /skill` listed it with the exact body; the generated config file kept `provider.omnirush`, `model`, the 11 plugins and no `mcp` key unchanged.
+- `POST /workspace/:id/mcp` with a supported server stores it for the engine plugin; after the project's engine reloads, the plugin's report lists it as allowed (pinned version), and entries off the list as blocked with the reason (`engine-plugin-bridge.e2e.test.ts`, `omnirush-ui-mcp-guard.e2e.test.ts`).
## Troubleshooting
@@ -139,17 +137,11 @@ The engine caches its skill catalog per project instance and needs an instance r
- The app lists `.opencode/skills`, `.opencode/skill` and `.claude/skills` under the git root, plus the global folders when the workspace is local. A skill placed above the git root is not a workspace skill.
- Two skills with the same name: the first one found wins (workspace before global).
-**An MCP server shows an error or Offline.**
-- Local servers: the command must be an absolute path or on the PATH of the desktop app (which is not your shell PATH). Prefer absolute paths such as `/usr/local/bin/node /path/to/server.mjs`. The server must speak JSON-RPC over stdio, newline-delimited, and answer `initialize` and `tools/list`.
-- Remote servers: the URL must start with `http://` or `https://` and must not contain whitespace. Sign-in errors show as Needs sign-in; use the card's Sign in action.
-- `engineSync.failures` on `GET /workspace/:id/mcp` (visible in Settings, Debug) lists the exact registration error. A 503 "deferred until active tasks finish" means a session was running; the server retries when the engine is idle.
-- Registration is skipped while the engine is busy to avoid replacing a tool set mid-turn. Wait for the running session to finish or reload the engine.
-
-**The MCP server is connected but its tools are missing from a diagnostics tool list.**
-`/experimental/tool/ids` only lists built-in and plugin tools. Use the card status and the server's own logs; the engine calls `tools/list` right after the handshake.
+**An MCP server shows Blocked.**
+The reason says why: not on the supported list, a version outside the supported range, a file or folder outside the project, a remote server, or a command the app cannot name (start it with `npx` or `uvx` and the package name). Edit the entry, or use one of the supported servers in Settings, MCP.
-**Removing an MCP server left tools behind in a running session.**
-The engine drops the registration immediately, but a session that already started a turn keeps its captured tool set until the turn ends.
+**An MCP server I just added does not show On yet.**
+It starts when the project's engine reloads (the app reloads it after an add). The status says "Checked when the project's next chat starts" until then.
**The app reports "Configuration is invalid at … V2 permissions are not supported by OmniRush V1", or a workspace answers `opencode_config_invalid`.**
The bundled engine is OpenCode V1 (pinned in `constants.json`). Since engine 1.18.32 a `permissions` key in a user-owned `opencode.json(c)` — top level, or under `agent`, `agents` or `mode.<name>` — is rejected instead of ignored. The server checks those files before spawning the engine: a `permissions` key in the global file (`~/.config/opencode/opencode.json(c)`, `config.json`, or the `OPENCODE_CONFIG_DIR` directory) stops startup with the message above naming the file; a `permissions` key in `<workspace>/.opencode/opencode.json(c)` or `<workspace>/opencode.json(c)` is logged as a warning, the engine still starts, server routes that read the engine for that workspace return `422 opencode_config_invalid` with the engine's message and the file path in `details`, and the native engine proxy passes the engine's own `400 ConfigInvalidError` body through unchanged. Other V2-only keys (`plugins`, `providers`, `websearch`, `warming`, …) are dropped with a "configuration compatibility diagnostic" warning in the engine log and do not block anything. Fix: rename `permissions` to `permission` (V1 rules) or remove it, then restart OmniRush.ai.
@@ -168,7 +160,7 @@ Yes. The 2.x engine kept them (and the 1.x sessions of earlier releases, which i
Provider and MCP sign-ins the engine kept as files in `~/.local/share/opencode/` (`auth.json`, `mcp-auth.json`) are copied into the engine's data directory (`<userData>/engine-data/omnirush/`) once, never over a file already there. The 2.x engine kept newer sign-ins inside its database; those are not copied and have to be signed in again.
**Where are the files?**
-- Server state directory: `~/.config/omnirush/` (or the directory of `OMNIRUSH_SERVER_CONFIG`), containing `runtime.sqlite` (runtime DB), `runtime-opencode-config.json` (engine-visible config) and the managed MCP vault.
+- Server state directory: `~/.config/omnirush/` (or the directory of `OMNIRUSH_SERVER_CONFIG`), containing `runtime.sqlite` (runtime DB), `runtime-opencode-config.json` (engine-visible config) and `mcp/` (the remembered MCP list, the plugin's reports and the app-added servers).
- Engine data: `<userData>/engine-data/omnirush/` (the `opencode.db` session database, snapshots, sign-ins, logs under `log/`), the app's own: the OmniRush CLI's engine keeps its data in `~/.local/share/omnirush/` and never sees the app's sessions. The engine runs with `XDG_DATA_HOME=<userData>/engine-data`; commands the agent runs get the user's own `XDG_DATA_HOME` back. `OMNIRUSH_ENGINE_DATA_HOME` overrides the location. The engine also reads the global opencode config directory (`~/.config/opencode/`, or `OPENCODE_CONFIG_DIR`) for the app's global skills and config.
- The 2.x engine's store of desktop 2.2.0 – 3.x: `~/.local/share/opencode/opencode.db` (read once by the import above, never written).
- Audit log: `<workspace>/.opencode/` audit entries record every skill and MCP change with the actor.
@@ -181,11 +173,9 @@ Provider and MCP sign-ins the engine kept as files in `~/.local/share/opencode/`
| Read a skill | `GET /workspace/:id/skills/:name` |
| Add or update a skill | `POST /workspace/:id/skills` `{ name, description, content }` |
| Remove a skill | `DELETE /workspace/:id/skills/:name` |
-| List MCP servers | `GET /workspace/:id/mcp` (items, `engineSync`, `managedOAuthState`) |
-| Add an MCP server | `POST /workspace/:id/mcp` `{ name, config }` |
-| Add a managed OAuth MCP server | `POST /workspace/:id/mcp/managed` `{ name, url, oauth }` |
+| List MCP servers | `GET /workspace/:id/mcp` (items with each one's `decision`, and `mcpPolicy`: `enabled`, `message`, `supported` presets, `decisions`) |
+| Add an MCP server | `POST /workspace/:id/mcp` `{ name, config }` (refused with the reason when not supported) |
| Pause or resume | `POST /workspace/:id/mcp/:name/enabled` `{ enabled }` |
-| Sign out of a server | `DELETE /workspace/:id/mcp/:name/auth` |
| Remove a server | `DELETE /workspace/:id/mcp/:name` |
| Reload the engine | `POST /workspace/:id/engine/reload` |