Skip to Content
OpenInspect
Configure repositories and environments

MCP servers

Give agents extra tools by registering local or remote MCP servers, routing remote ones through OpenInspect with shared or per-user credentials, scoping them to repositories, and keeping local servers fast to start.

Last reviewed View as MarkdownEdit on GitHubGive feedback

MCP servers add tools to the agent (a browser, a documentation index, an internal API) that OpenInspect starts or connects to inside each session.

Settings, MCP Servers: a remote server with a URL and a command-based server, each with a scope and an enable toggle
Settings › MCP Servers. A remote HTTP server and a command server, each scoped globally or to a repository.

Prerequisites

  • The mcp_servers.manage permission to add, edit, enable, disable, or delete servers, revoke users' personal connections, and see the names of saved credentials. Users with only mcp_servers.read can view the list, but not credential names.
  • For repository-scoped servers, at least one connected repository. The form shows "No repositories available. Connect a GitHub integration first." otherwise; see GitHub.

Adding a server

Open the form

Go to Settings › MCP Servers and click Add Server; the New MCP Server form opens.

Name and type

Enter a name (for example playwright or context7) and choose Local or Remote.

Connection details

For a local server, enter the command as a space-separated command and arguments, such as npx -y @playwright/mcp. Use quotes for arguments that contain spaces. Optionally add Environment Variables as key and value rows.

For a remote server, enter the URL, such as https://mcp.example.com/mcp, choose its Authentication, and decide whether to Route through Open Inspect (see Authentication and routing). With Shared service credentials, optionally add HTTP Headers as name and value rows.

Availability and state

Choose "All repositories" (available in every agent session) or "Selected repositories only" and tick the repositories. Leave Enabled on, then click Add Server.

Server types

TypeYou provideOpenInspect does
LocalA command as an argument list, plus optional environment variablesPrepares the package (for npx commands) and starts the process inside the sandbox
RemoteA URL, an authentication mode, plus optional headersConnects the agent to the URL from inside the sandbox, or through OpenInspect when routed

Authentication and routing

A remote server uses one of three authentication modes, chosen under Authentication:

AuthenticationAPI authModeWhat the server receives
No upstream authenticationnoneNo credentials.
Shared service credentialsservice_credentialsThe server's saved headers, the same for every session. The default, and the mode of remote servers created before these modes existed.
Each user's OAuth connectionuser_oauthThe OAuth connection of the person whose prompt is running; see Personal connections. Always routed.

Route through Open Inspect sends the agent's requests to the server through the OpenInspect control plane instead of straight from the sandbox. The sandbox authenticates to OpenInspect with its own session token and never holds the upstream credential: a routed server's headers stay in the control plane, which adds them to each request it forwards. Existing remote servers keep connecting directly until you turn routing on. Disabling a routed server refuses new calls at once, including from running sessions. Calls already forwarded are not cut off at once. While a call waits for the server to start responding, which can take up to 5 minutes, OpenInspect does not recheck it. Once the response starts, and for a response that is already streaming, data can keep flowing for up to 10 seconds until the next authority check ends it.

A routed server must speak Streamable HTTP at a public HTTPS URL: no IP address, single-label or localhost, .local, or .internal hostname, credentials in the URL, fragment, or port other than 443. The hostname is checked as written; OpenInspect does not check the addresses it resolves to. Routed requests have per-sandbox rate and size limits; see Limits.

For Each user's OAuth connection, also enter the OAuth issuer. Leave OAuth resource blank: it defaults to the server URL, and connecting fails for any other value. When you change an existing server's URL, clear OAuth resource or set it to the new URL. The server must publish OAuth metadata that names that issuer and resource exactly, keep its token and registration endpoints on the issuer's origin and its authorization endpoint on the issuer's registrable domain (for example foo.test for an issuer at api.foo.test), and support dynamic client registration for a public client with S256 PKCE.

Saved credentials

Environment variables and headers are credentials: they are stored encrypted on the server side. A local server's environment variables and an unrouted remote server's headers are injected into the session when the server is prepared; a routed server's headers stay in the control plane. They are write-only. After you save a value, neither the settings page nor the API returns it to anyone.

When someone with mcp_servers.manage edits a server, the form lists each saved environment variable or header by name, with its value hidden. Names are locked. Users with only mcp_servers.read see neither names nor values.

ToDo this in the edit form
Keep a saved valueLeave its row blank.
Replace a valueEnter a new value in its row.
Remove a credentialRemove its row.
Rename a credentialRemove its row, then click + Add and enter the new name with its value.
Add a credentialClick + Add and enter a name and value.

Nothing changes until you click Save Changes. Header names match without regard to case, so a new authorization row replaces a saved Authorization header. Environment variable names are case-sensitive. Switching between Local and Remote hides the saved rows, because headers and environment variables are not interchangeable. Switching back before saving restores them, but saving under the other type deletes the saved credentials. The same applies to headers when you switch a remote server's Authentication away from Shared service credentials: only that mode accepts headers.

API clients make the same per-name edits by sending keepCredentialKeys with PUT /mcp-servers/:id. Listed names keep their saved values, names sent in env or headers take the new values, and saved names that are neither kept nor sent are deleted. Without keepCredentialKeys, the credentials sent replace the whole saved set. If the saved credentials cannot be decrypted, for example after the encryption key changed, a request with keepCredentialKeys is refused with 409 and nothing changes; send the full set without it to replace them.

Scope and enablement

ControlEffect
All repositoriesThe server is available in every agent session.
Selected repositories onlyThe server is available only in sessions for the chosen repositories. At least one must be selected.
Enabled switchA disabled server stays configured but is not passed to any session. Toggle it from the list without opening the form.

Edit a server from the list to change any field and click Save Changes; see Saved credentials for environment variables and headers. Deleting a server cannot be undone.

A server cannot be deleted while users have personal connections to it. Turn it off, click Revoke connections on its row and confirm, then delete it. Revoking disconnects every user's personal connection to that server; it does not revoke their accounts at the external service. Revoke connections appears on every disabled remote server, because connections made under an earlier Each user's OAuth connection setting still block deletion after the mode changes. If such a server was changed to Local, the button is hidden: change it back to Remote first, or call POST /mcp-servers/:id/revoke-connections.

Personal connections

When a server uses Each user's OAuth connection, each person connects their own account under Settings › Connections (Your MCP connections). Click Connect and approve access at the service. Reconnect keeps the current connection working until the new approval completes. Disconnect stops use through OpenInspect but does not revoke the account at the external service. Connecting requires the web app to be served over HTTPS.

In a session, the server acts as the person whose prompt is running. Only prompts a person sends from the web or Slack can use personal connections; turns started by automations, GitHub, or Linear cannot. Before forwarding each call, OpenInspect checks that this person is not suspended and can still read and collaborate in the session. When several people prompt one session, each turn uses its own author's connection. A child session uses the connection only when the parent session's own agent spawned it. The proxy authenticates the sandbox, not the process inside it, so a process left running from an earlier turn can make calls with the active author's connection during that author's turn. Don't use personal connections in a session shared with people or prompts you don't trust.

Personal servers work only in OpenCode and Claude Agent sessions whose sandbox image is at runtime generation 80 or later. In a Codex session, or on an older image or snapshot, they are left out of the agent's configuration, and each prompt records an mcp warning naming them, shown in the session and in Slack completions. Other MCP servers remain available.

Changing a server's URL, authentication, OAuth issuer or resource, routing, headers, or repository scope marks existing connections Reconnect required, and routed calls from sessions that are already running stop working. Renaming a server does not. To use the changed server, start a new session; if it still uses Each user's OAuth connection, reconnect first. After a switch to shared credentials or no authentication, no reconnection is needed, and Reconnect is unavailable.

While a person has a live connection, their account cannot be merged into another or deleted; see Merging duplicate accounts.

How servers reach the agent

  • OpenCode: enabled servers in scope are written into the session's OpenCode configuration when the agent starts. Personal servers are connected only for the turns that may use them and disconnected afterwards.
  • Claude Agent: the same servers are passed to the harness. OpenInspect's own tools reach Claude Agent through a built-in server named oi, separate from the servers you register. A turn that may use personal servers restarts the agent process with them.
  • Codex: the same servers are translated to Codex's own server configuration. A server named oi, or a remote server whose URL carries credentials, a query string, or a fragment, is refused, so put credentials in headers. OpenInspect's own tools reach Codex as built-in tools in an oi namespace. Personal servers are not loaded.

Local servers' commands, arguments, and environment variables, and unrouted remote servers' URLs and headers, are passed through as configured. A routed server reaches the agent as an OpenInspect URL that authenticates with the sandbox's own token. Changes apply to new sessions; a running session keeps the server set it started with, though a routed server stops working in it once it is disabled or its connection settings change.

Startup cost of local servers

Before starting a local npx server, OpenInspect checks the sandbox's global npm installation. An exact package version that is already installed with intact executable links is reused, including after a snapshot restore. Only missing or mismatched packages are installed, and a failed or interrupted install is retried rather than treated as installed.

To remove that install from the first session's startup, pin the same version in the command and in the repository's .openinspect/setup.sh (or the setup hook used by its environment), then rebuild the prebuilt image:

# .openinspect/setup.sh
npm install --global @example/mcp-server@1.2.3

Configure the matching command as npx -y @example/mcp-server@1.2.3. MCP settings are not baked into images automatically; the setup script is what puts the package there. Changing the pinned version causes an install on every session until the image is rebuilt with the new version.

Unversioned packages are refreshed every boot

A command without a version, or with a tag such as latest, is refreshed once per sandbox boot. The install is reused across agent restarts within that boot, but not across snapshot restores. Pin a version if startup time matters.

Remote servers are unaffected by any of this. Unsupported npx option forms are left to npx without eager installation, so npx may still resolve registry metadata or populate its own cache.

See lifecycle scripts and prebuilt images for how setup.sh and image builds fit together.

Troubleshooting

Next steps

On this page