Matrix MCP

Give your coding agent a computer that keeps running. Matrix MCP lets it run commands, work with files, manage terminals, and read chats on your Matrix computer.

Hosted MCP uses Streamable HTTP at https://api.matrix-os.com/mcp. Your coding agent connects directly and signs in through browser OAuth. This does not require installing the Matrix CLI. Commands and file operations run on the selected Matrix computer, not on the agent's local computer.

Set up your local computer

If your release includes the local-setup page, open Settings → Matrix CLI & MCP in Web Canvas, Web Desktop, or Electron Desktop. The Getting started checklist also has a Set up local CLI, MCP & skills shortcut to that page. If this page is absent, use the stdio setup directly; the instructions below do not require a Settings shortcut.

Install on your local computer, not your Matrix VPS. The page brings together CLI installation, direct MCP setup, and plugins that bundle workflow skills. Copy buttons only copy instructions; they do not run installers. Opening setup does not mark any onboarding step complete, and Matrix cannot detect local installations from this page.

Run terminal commands in your local terminal and Claude slash commands inside Claude Code. On a phone, open these instructions on the computer you want to set up. The separate Services/Custom MCP and Skills settings manage connections and skills inside Matrix, not these local clients.

Choose your coding client

Once hosted MCP is enabled and browser sign-in has been verified, use direct MCP for tools only, or the Matrix OS plugin for tools plus workflow skills. Install one connection per client to avoid duplicate tools.

Buttons open an installed desktop client and ask you to confirm. Browser OAuth and consent still follow; one click does not silently authorize computer access. On mobile, use the copyable setup on your desktop. End-to-end sign-in remains unverified until hosted rollout.

Codex

codex mcp add matrix --url https://api.matrix-os.com/mcp
codex mcp login matrix

Or add the server to your Codex configuration, then run the login command:

[mcp_servers.matrix]
url = "https://api.matrix-os.com/mcp"
tool_timeout_sec = 60

Use the server name shown by your client when logging in to a plugin-provided connection. See the official Codex MCP guide.

Claude Code

claude mcp add --transport http --scope user matrix https://api.matrix-os.com/mcp

Open Claude Code, run /mcp, select Matrix, and complete browser authentication. See the official Claude Code MCP guide. Other clients need support for authenticated Streamable HTTP and a registration method compatible with the configured authorization server; a client-specific connector is not installed by the skills pack.

Cursor

Confirm the server URL, then complete browser authentication when prompted. If the button does not open Cursor, merge this entry into your existing ~/.cursor/mcp.json:

{
  "mcpServers": {
    "matrix": { "url": "https://api.matrix-os.com/mcp" }
  }
}

Cursor's install-link documentation.

VS Code / Copilot

Confirm installation, start the server, and follow browser sign-in. Or run:

code --add-mcp '{"name":"matrix","type":"http","url":"https://api.matrix-os.com/mcp"}'

VS Code's MCP setup guide.

Other MCP clients

Choose a remote Streamable HTTP server, enter https://api.matrix-os.com/mcp, and authenticate through the client's browser OAuth flow. Client registration must be compatible with Matrix's authorization server. Do not select stdio or paste a bearer token into a config file.

Install the Matrix OS plugin

The plugin bundles the same MCP connection with setup, cloud-work, and GitHub-project skills. No separate Matrix CLI installation is needed for hosted tools. The hosted rollout warning above applies to plugin installation too.

Codex plugin

Add Matrix's marketplace:

codex plugin marketplace add HamedMP/matrix-os

Open /plugins, choose the Matrix OS marketplace, and install matrix-os. In the desktop app, select that marketplace in the Plugins directory. Start a new session and authenticate the bundled connection. Use its displayed server name if running codex mcp login <configured-server-name>.

Codex marketplace setup.

Claude Code plugin

Run these commands inside Claude Code:

/plugin marketplace add HamedMP/matrix-os
/plugin install matrix-os@matrix-os

Start a new session, open /mcp, select the Matrix connection, and sign in.

Claude Code marketplace setup.

Consent and authentication

The matrix:computer scope grants broad remote-computer access: an agent can run arbitrary commands, change files, control terminals, and read chats on computers your account can access. Only connect clients you trust. Matrix rechecks computer access for every call; permission to use MCP does not create access to another user's computer.

Do not paste access tokens, OAuth codes, or local credential files into chat or plugin configuration. HTTP OAuth and matrix login are separate: CLI login does not repair an HTTP authentication failure. Clients may refresh tokens when their authorization server supports it; otherwise reconnect through browser login. Local JWT verification can accept an already-issued token until expiry after provider revocation, so use short-lived access tokens for this high-privilege scope.

MCP cannot disable the agent host's local shell. Configure the host's permissions separately if you require remote-only execution.

Try it

Use these checks after hosted activation, on a disposable Matrix computer you own. They also apply to the stdio connection, which uses CLI authentication.

1. Call list_computers, then choose a returned runtimeSlot explicitly.
2. Call run_command with that slot as computer and "command": ["pwd"]. Confirm the output describes the Matrix computer.
3. Create a uniquely named terminal and tab. Use the returned stable tab ID to select it, then send pwd followed by a newline and observe Matrix's Terminal UI.
4. Upload a uniquely named smoke-test file in an existing Matrix-home directory, read/download it, and compare content. Keep overwrite: false; repeating the upload must refuse replacement.
5. List/search/get chats only when that read-only context is needed.

Hosted captured commands default to and cap at 45 seconds. The HTTP request deadline is 55 seconds. Use persistent terminals for builds, interactive programs, and longer tasks. Terminal input is fire-and-observe: there is no terminal-output reader in this release; captured output comes from run_command. A timeout or disconnect does not prove that a remote side effect was undone—inspect state before retrying.

Text reads are capped at 256 KiB, transfers at 1 MiB, directory listings at 500 entries, terminal input at 60,000 bytes, and chat pages at 100 items. File tools return/accept content rather than accessing arbitrary paths on the agent's local computer. All chat tools are read-only. Both the CLI and hosted adapters expose the same 15 tools, with the shorter captured-command budget applying only to HTTP. The matching gateway release is required for stable-tab selection and cwd fixes.