MCP services

Read this page when you want an Arc-managed agent to use a third-party MCP server, such as a code-analysis or database tool that runs on the operator's computer. Arc starts the server as a local process (a stdio MCP service), checks its tool catalog, and offers its tools to the agents you grant it to.

This is the opposite direction from arc mcp. arc mcp gives agents in other apps (Claude Code, Codex, Cursor, Gemini, Muse Code and others) Arc's coordination tools; see Connections and harness setup. A service you configure here is used only by agents Arc runs itself, on an API key, a self-hosted server or a model file, and it does not configure tools in any other app.

What you need

• A local stdio MCP server that you have installed and can start with a command. Arc does not install servers or their dependencies. Remote HTTP and SSE servers can be recorded but are always saved disabled and cannot be granted.
• An Arc-managed agent that can run commands: its room set to Full Access and a project folder chosen for it. A service runs with the agent's own access, and a grant never widens it. An agent in a Safe room, or a chat-only agent without a folder, cannot see or call a service.

Add or import a service

Open Settings → Tools (MCP). The MCP services page lists each service with its transport, whether it is enabled, its tested catalog and its live sessions, and offers Refresh, Add service and Import from other agents….

1. Choose Add service. Give the service a Label and, optionally, a Description; the first part of the description appears in the agent's instructions. The label also names the service's tools (see below).
2. Keep the transport at stdio (local command). Enter the Command and its Arguments (JSON array). Arguments are passed to the program one by one, not through a shell, so do not type a shell command line into the argument field.
3. Optionally set a Working directory, as an absolute path; without one, the server starts in the agent's project folder. Add Environment variables, marking sensitive values as Secret (see below).
4. Save, then choose Test on the service's card.

The server receives a minimal environment (PATH, HOME, USERPROFILE, TMP, TEMP, TMPDIR, SystemRoot and LANG) plus the variables you set, so add any variable it needs instead of assuming it inherits your terminal's. When a bare command is not found, Arc also looks in common install folders such as /opt/homebrew/bin, /usr/local/bin and ~/.local/bin; an absolute path to the executable always works.

Test launches the command in a temporary connection, negotiates MCP, fetches the tool catalog, saves it and closes the connection. Its result shows whether the connection was verified, the protocol version, the tools and the server's identity. A passing test proves the server starts and lists its tools. It does not run any of those tools or prove that whatever they rely on is ready. Saving or importing a service neither starts it nor grants it to any agent.

A service's card also has Disable or Enable, Edit and Delete. Delete removes the service, its catalog and its grants at once, without asking.

Import from other agents

Import from other agents… copies registrations you already have elsewhere. It reads Claude Code (~/.claude.json), Cursor (~/.cursor/mcp.json), Codex (config.toml in ~/.codex or $CODEX_HOME), Gemini (~/.gemini/settings.json) and Muse Code (its settings.json, including a legacy mcp_servers map). Enter an optional Workspace path to include a project's .mcp.json, .cursor/mcp.json and .gemini/settings.json too. Choose Preview to see each entry's source, command, arguments, working directory and environment, select the ones you want, then choose Import selected. A preview expires after ten minutes.

Arc only reads these files; it never changes them. Arc's own registration starts unselected, and so does any entry Arc cannot run as it stands. What an import does not carry over:

• Remote entries. HTTP and SSE registrations arrive disabled, without their URL credentials or headers.
• Other apps' approval settings. They grant nothing in Arc.
• Credentials typed into arguments. They are scrubbed, and the service needs repair before it can launch.
• Missing values. Environment references resolve from Arc Desktop's own environment. A missing value, or a relative working directory with no workspace path, needs repair.

Variables whose names look like credentials (containing TOKEN, SECRET, PASSWORD, API_KEY and similar) are marked Secret and moved into the operating system's credential store; untick one to keep it as a plain value. A Codex tool_timeout_sec becomes the service's Hard timeout.

Keep secrets out of configuration

Set a variable to Secret for API keys, tokens and passwords. Arc stores each secret in the operating system's credential store (the Keychain on macOS, Credential Manager on Windows), and the service configuration keeps only a reference to it. A secret must be non-empty, contain no NUL character and fit within 2,560 bytes; intentional whitespace is kept. Leaving a secret field blank while editing keeps the stored secret. Plain variables are stored in Arc's database with the rest of the configuration.

Arc removes the secrets it knows about from diagnostics and from the results it keeps, and marks where it did. It cannot recognise every sensitive value a server might print, so treat a service's output with the same care as its configuration.

Grant a service to an agent

In the room, open the agent's ⋯ menu, choose Agent settings…, and tick the service under MCP tools. A service can be granted when it is enabled, uses stdio and has a current tested catalog; the panel shows the reason under any service that cannot. Unticking a service always works. A grant belongs to that agent in that room only: the same agent in another room, or another agent in this room, needs its own grant.

When the agent's room is not Full Access, the panel says so. The grant is saved, but its tools stay hidden from the agent until the room is Full Access.

A tested catalog becomes stale when you change how the service launches or disable it. Agents with a grant lose its tools until you test the service again; after Disable and Enable, test it again too. Changing only the label keeps the catalog.

Use a service as an agent

A granted agent's instructions name each service it can use. Its tools reach the model as <namespace>__<tool>, for example rea__binary_session for the binary_session tool of a service labelled REA. The namespace comes from the label when the service is created, in lower case and at most 24 characters, is made unique, and never changes afterwards, so renaming a service cannot point a remembered tool name at another server. A name gets a short hash only when it would exceed 64 characters or when two of the server's tool names would otherwise read the same.

Find a service's tools with tool search, searching for the service name or its namespace and the operation you need, then describe or call the tool:

arc_search_tools({"query": "rea binary session"})

The first call opens the agent's own connection to the service. A call returns the service's output and a retained record with the result's output_id, size, digest, and whether it is complete and redacted. The model sees at most 48 KiB of the result, or 4 KiB on the compact tool surface some self-hosted models use; a larger result arrives as the largest preview that fits, marked incomplete. Read the rest with the managed runtime tool mcp_output:

mcp_output({"service_id": "<service id from the result>", "output_id": "<output id from the result>", "offset": 0})

Pages end on character boundaries, so text is the exact page; pass next_offset to continue until eof. An agent reads only its own outputs, and each read checks its current room access and grants again.

When the service reports that a call failed, the result has ok: false, error: "tool_error" and the service's own message in output.content; read it and retry only if the message says the operation did not run. Arc's own refusals use other codes, such as service_access_denied when the agent no longer has the grant or access, and service_session_limit when the live session limit is reached.

Watch and keep results

In the room's Work tab, expand the agent's session to see its MCP tools card. Each call shows the service and tool, its status, elapsed time, any progress the server reports, and the size of its result, noting when credentials were redacted. While a call runs, Cancel turn stops the agent's turn. View output opens a retained result. Save as artifact saves a complete result in the room; a result too large for one artifact is saved as ordered parts with an index artifact, in one step, up to 512 parts.

Arc keeps each retained result, up to 32 MiB, in its data folder; a larger result is not kept, and the call says so. Retained results are not deleted automatically.

Connections, cancellation and recovery

Each agent has its own connection to each service it uses. The connection opens on first use and keeps the server's state across turns and checkpoints. While the agent has a live connection, Agent settings… → MCP tools offers:

• Disconnect closes the connection and keeps the grant. The next call reconnects.
• Reset discards the server-held state for this agent and opens a fresh connection at once.

Unticking the grant, disabling or editing the service, removing the agent, switching the room to Safe, stopping the conversation or stopping the hub also closes connections; Arc finishes closing them in the background, so other agents are not held up. A reconnection is reported as a new session, and anything the server held in memory, such as an open file, is gone; reopen it before relying on earlier references. A folder change updates the server's roots without reconnecting unless it changes the working directory. Roots tell the server which folders the work is about; they do not confine what a Full Access service can reach.

Cancelling a turn sends the server an MCP cancellation and abandons the call. New calls to that service wait through a short grace period, 10 seconds by default, unless the server answers first. If it never answers, the next result warns that the cancelled work may still have been running. Arc never repeats an interrupted call.

Limits

Set the Live session limit on the MCP services page; set the others under Advanced when you add or edit a service.

The 60-second connection timeout leaves room for a first-run package download, such as a server started with npx -y; raise it for a slower one. When the live session limit is reached, a new connection is refused rather than closing another one: disconnect an unused session or raise the limit. A catalog may hold up to 10,000 tools and 32 MiB. Progress messages are what the server reports, not necessarily a percentage.

What is not supported

Remote HTTP and SSE servers, OAuth sign-in, and the MCP features for sampling, elicitation, tasks, and running resources or prompts are not available for services. Arc speaks MCP protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 and refuses a server that offers another one. A tool whose schema needs features Arc cannot pass to models is listed as incompatible. Images in a result are kept with it but are not sent to the model as pictures.

Example: REA

REA is a reverse-engineering MCP server started with Node.js. With an existing REA checkout, configure it like this, using the absolute paths on your machine:

{
  "transport": "stdio",
  "command": "/absolute/path/to/node",
  "args": ["/absolute/path/to/REA/scripts/rea.mjs", "mcp"],
  "cwd": "/absolute/path/to/REA",
  "env": {
    "GHIDRA_INSTALL_DIR": "/absolute/path/to/ghidra",
    "JAVA_HOME": "/absolute/path/to/java/home"
  }
}

In the form, command is Command, args is Arguments (JSON array), cwd is Working directory and env holds Environment variables. The two variables are needed only for Ghidra native analysis; inspecting JavaScript statically works without them. REA and its analysis tools are separate installations, and a Test never runs a target program. Grant the service to an agent, ask it to check REA's status before opening a target and to close an open binary when the analysis is done. Its tools appear as rea__<tool>.

For custom clients

Service management, grants and output reads are operator routes: they need the operator key and are listed under MCP services and room agent memberships. Imports and secret entry happen only in Arc Desktop. There is no MCP tool, CLI command or Python method for managing services, and an agent driving Arc Desktop with arc_ui_command sees the MCP services settings and the grant checkboxes as operator-only. Arc records mcp.service_changed, mcp.grants_changed, mcp.session_changed and mcp.tool_called events in the affected rooms; see the event vocabulary.

Related

• Workspaces, shell and documents for what Full Access allows
• Managed agents, runs and completion for seating agents
• Managed runtime tools, including mcp_output
• Muse Code and Connections and harness setup for the other direction, Arc's tools inside other apps