Add MCP servers

On this page

An MCP server lets Codex or Claude use tools from another service, such as searching your team's documents or updating an issue in your tracker. Add a supported remote server in boxes.dev to make its tools available across your project's Template box and devboxes. If the service supplies a marketplace plugin rather than an MCP server URL or setup command, follow Install agent plugins.

Add a connection

Get the server URL or setup command from the service you want to connect, then:

In the desktop app, select your project and open Integrations → MCPs.
Choose Add MCP and paste the URL or the provider's Codex or Claude setup command, then choose Continue.
Name the connection. Keep This project selected, or choose All projects if you want to use the same server and service account across your projects.
If Advanced opens to request an API key or header, enter the values supplied by the provider.
Under Add to, choose Codex, Claude, or both. Choose Add MCP and complete any requested provider sign-in.

boxes.dev will detect the supported connection type and authentication method. You can use Advanced to edit the URL, authentication method, and the name your agents will use.

For OAuth connections, Codex and Claude each need their own authorization, so connecting both usually means approving access twice in your browser. API-key and unauthenticated servers do not require that browser sign-in.

The connection's row will show a separate status for each agent. boxes.dev will keep the connection and its credentials current on the applicable machines, including new devboxes and sleeping machines after they wake. You don't need a snapshot. Project-scoped connections let you use different service accounts in different projects.

Keep connections current

Open Integrations → MCPs to manage your saved connections. Opening the page will not wake a machine.

To add an agent, select its button on the connection row.
To renew sign-in or stop an agent from using the connection, open that agent's button menu and choose Reauthorize, Remove from Codex, or Remove from Claude.
To edit the server definition or headers, or remove the connection from both agents, use the row's ⋯ menu.

Add a connection from a terminal

You can also add supported remote HTTP connections from a terminal on a Template box or devbox:

codex mcp add <name> --url <url>
claude mcp add --transport http <name> <url>

Run the command for the agent you want to use, replacing the placeholders with your server's name and URL. It will add the connection to the current project's central list. Finish authorization in the desktop app or follow the displayed instructions on your computer.

To enable both agents, run both commands with the same name, URL, and authentication settings, including any API-key headers. The second command will add its agent to the existing project connection. Repeating a matching command will preserve the connection and current sign-in; OAuth still needs separate authorization for each agent.

For an All projects connection, or when the same name has different settings, add the agent through the existing row in Integrations → MCPs. Choose another name if you need a separate connection.

Handle an existing machine-local connection

If an agent already has an MCP with the same name configured directly on a machine, its button may say Already set up in Codex or Already set up in Claude. Choose Move to boxes.dev to replace matching copies with the connection and sign-in saved in boxes.dev.

Approve the move separately for each agent. Sleeping machines will apply it when they next connect. A copy with a different URL, transport, authentication setup, disabled state, or customized configuration will be left unchanged. Choose Rename MCP if you want to keep both connections.

Connections that stay on the Template box

Local stdio servers, legacy SSE servers, custom OAuth clients, and unsupported command options remain Template-managed. Configure these through the agent's native tools on your Template box, then save a snapshot for future devboxes. Existing devboxes will keep their own configuration.

Expand Template-managed MCPs on the MCP page to inspect the Template box's connections; this may wake it. If that inventory cannot load, you can still edit the central connections. Member projects have no personal Template box, so they show only the central list. You can still use native agent tools to install an unsupported MCP on a member devbox, but that installation will stay on that devbox.

When a connection's sign-in expires, open Integrations → MCPs. The repair depends on where the connection lives:

For a central connection, including a definition copied from a Team Template, choose Reauthorize from the Codex or Claude button menu on its row. boxes.dev will send your renewed sign-in to the applicable devboxes.
For a Template-managed connection, reauthorize it on the Template box and save a snapshot for future devboxes. Existing devboxes will need their own repair to use that MCP.
For a machine-local connection copied in a Team Template's saved environment, follow the notice to ask a Team Template admin to repair it in the template.

If Codex reports an expired MCP sign-in during a thread, the notice above the composer offers Open MCPs as a shortcut to this page. Dismissing the notice will hide that server's current warning across the project; it will not reconnect the service. A later expiration after a successful connection can show a new warning.