> ## Documentation Index > Fetch the complete documentation index at: https://infisical.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP servers > Remote MCP servers that an AI agent can use during a session without holding their credentials. An MCP service lets an agent use a remote [MCP server](https://modelcontextprotocol.io/), such as Linear's or Notion's, during a [session](https://infisical.com/docs/documentation/platform/agent-vault/sessions). It's one of the two types of [service](https://infisical.com/docs/documentation/platform/agent-vault/services) you can add to an access bundle. The other type, an HTTP service, covers a web API that the agent calls directly. You add the MCP server to your agent with its real URL and no credentials. When the agent connects to the server, the [proxy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md) attaches the service's credential, so the agent can call the server's tools without ever holding the credential. ## Prerequisites * The [Admin role](https://infisical.com/docs/documentation/platform/agent-vault/access-control.md#product-membership) in your Agent Vault project * An [access bundle](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md) to add the MCP server to * A running [proxy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#create-a-proxy-and-start-it) that your agent can reach * An account with the MCP server's provider, or a token the server accepts ## Add an MCP server **Step 1** In your Agent Vault project, go to **Access Bundles**. Select your access bundle, then select **Add Service**. **Step 2** On the **Choose a template** panel, pick a template under **MCP Servers**, or select **Custom MCP Server** to connect any other remote MCP server. ![The Choose a template panel filtered to MCP Servers, showing Custom MCP Server, GitHub MCP, Linear MCP, Notion MCP, and Sentry MCP](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/mcp-template-picker.png) **Step 3** On the **Details** step, enter a **Name**, and check the [**Transport** and **Server URL**](#server-url-and-transport). A template fills in the transport and server URL for you. Select **Continue**. ![The Details step of the notion MCP service, with Streamable HTTP as the transport and https://mcp.notion.com/mcp as the server URL](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/mcp-service-details.png) **Step 4** On the **Credential** step, pick a **Credential Type** and set up the [credential](#credential-types). Select **Continue**. ![The Credential step of the notion MCP service, with Bearer Token as the credential type, a token that uses the NOTION\_TOKEN variable, and the Member provided toggle off](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/mcp-service-credential.png) **Step 5** On the **Tools** step, choose which of the server's [tools agents can call](#allowed-tools). Select **Continue**. ![The Tools step of the notion MCP service, with All Tools turned on](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/mcp-service-tools.png) **Step 6** On the **Review** step, select **Add Service**. The service appears in the bundle's list with the type **MCP Server**. ![The support-triage access bundle in the Customer Support project, listing slack and zendesk as HTTP APIs and linear and notion as MCP servers, with a Needs Reauthorization badge on linear](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/access-bundle-mcp-services.png) Next, [connect your agent](#connect-your-agent) to the MCP server. ## Server URL and transport * **Server URL:** The URL your agent connects to, such as `https://mcp.linear.app/mcp` (it must start with `https://`, and can't include a username, password, query string, or fragment) * **Transport:** **Streamable HTTP** for most servers, or **SSE** if the server uses the older HTTP+SSE transport The service covers every request to the server URL's host, whatever the path. If the URL includes a port other than `443`, the service covers only that port. Two services in the same access bundle can't cover the same host, as described in [host conflicts](https://infisical.com/docs/documentation/platform/agent-vault/http-apis.md#host-conflicts). ## Credential types ### OAuth With OAuth, you sign in to the provider from Infisical, and Infisical stores the tokens the provider returns. If the provider also returns a refresh token, Infisical renews the access token before the token expires. If the provider doesn't return one, [reauthorize the service](#troubleshooting) when the access token expires or the server rejects it. The proxy only receives the access token, and the agent never receives any token. **Step 1** Under **Credential Type**, select **OAuth**, then select **Authorize**. ![The Credential step of a new Linear MCP service, with OAuth as the credential type, an Authorize button, and the Member provided toggle off](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/mcp-oauth-authorize.png) > [!NOTE] > > Some servers, such as GitHub's, don't let Infisical register itself as an OAuth client. For these servers, Infisical asks for an OAuth app of your own instead. Create an OAuth app with the provider, and set its redirect URI to the **Redirect URI** that Infisical shows. Then enter the app's **Client ID** and **Client Secret** (leave **Client Secret** empty for a public client), and authorize again. **Step 2** In the pop-up window, sign in to the provider and approve access. **Step 3** When Infisical shows **Authorized** and the scopes the provider granted, select **Continue**. **Continue** stays disabled until the authorization succeeds. ![The Credential step of the linear MCP service, showing Authorized with the read and write scopes and a Reauthorize button](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/mcp-oauth-authorized.png) > [!WARNING] > > Every session that uses the access bundle calls tools as the account you signed in with. Sign in with an account that has only the access your agents need, or [leave the sign-in to each member](#leave-the-credential-to-each-member). ### Bearer token With a Bearer token, you paste a token the MCP server accepts into **Token**, such as a [GitHub personal access token](https://github.com/settings/tokens) for GitHub MCP. The proxy sends the token as `Authorization: Bearer `. To send the token in a different header or with a different prefix, expand **Advanced Options** and change **Header Name** or **Prefix**. To use a token that several services share, type `{{` in **Token** and select a [variable](https://infisical.com/docs/documentation/platform/agent-vault/variables.md). ### Leave the credential to each member By default, every session calls the server's tools as the same account. If each member should use their own account instead, turn on **Member provided** next to **Token** or **Authorization**. You don't sign in or enter a token yourself. Each member then [sets up their personal values](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md#set-up-your-personal-values) for the service: * **Bearer token:** Each member enters their own token * **OAuth:** Each member connects their own account to the provider A session uses the credential of the member who created it. If a machine identity creates the session [on behalf of a user](https://infisical.com/docs/documentation/platform/agent-vault/sessions-on-behalf-of-users.md), the session uses that user's credential. Until a member sets up the service, the proxy refuses their sessions' requests to it. A machine identity can't connect an OAuth account, so its own sessions can't use an OAuth service that each member signs in to. When you save an OAuth service with **Member provided** on, Infisical checks that the server supports OAuth. If the server doesn't let Infisical register as an OAuth client, the save fails with a message that says so, and the **Credential** step shows the fields for an OAuth app of your own. Every member then signs in with that app. To set it up: **Step 1** Create an OAuth app with the provider, and set its redirect URI to the **Redirect URI** that Infisical shows. **Step 2** Enter the app's **Client ID** and **Client Secret** on the **Credential** step. **Step 3** Continue to the **Review** step, then select **Add Service** again, or **Save** if you're editing the service. > [!WARNING] > > Some edits remove the credentials members already set up, and Infisical asks you to confirm before it saves them: > > * Turning **Member provided** on for an OAuth service you connected removes your connection > * Turning **Member provided** off removes every member's credential, and every session then uses your account or token > * Changing the credential type, or for OAuth, the **Server URL** or the OAuth app, removes every member's credential, so each member has to set up the service again ## Custom headers If the MCP server needs another header besides the credential, such as an organization ID, add it as a custom header. The proxy adds custom headers to every request to the server, whichever auth method the service uses. **Step 1** On the **Credential** step, expand **Advanced Options** and select **Add Custom Header**. **Step 2** Enter the header's **Name**, an optional **Prefix**, and the **Value**. To use a [variable](https://infisical.com/docs/documentation/platform/agent-vault/variables.md), type `{{` in **Value**. Infisical won't save a custom header with the same name as the credential's header, which is `Authorization` unless you changed a Bearer token's **Header Name**. Infisical also won't save a header that the proxy sets itself, such as `Host` or `Content-Length`. ## Allowed tools By default, agents can call every tool the MCP server offers. To keep agents away from tools they shouldn't use, such as tools that delete data, allow only the tools you select. The list applies to every session that uses the service. **Step 1** On the **Tools** step, turn off **All Tools**. **Step 2** Infisical loads the server's list of tools with the service's credential. In **Allowed Tools**, select the tools that agents can call. If the credential is [member provided](#leave-the-credential-to-each-member), Infisical has no credential of its own to load the list with. Select **Load Tools** next to **Allowed Tools**, then enter your own token, or for OAuth, sign in with your own account. Infisical uses it only to load the list and doesn't save it. **Step 3** To allow a tool that the list doesn't include, type the tool's exact name in **Allowed Tools**, then select the option to add it. A tool name can contain only letters, numbers, underscores, hyphens, and dots, so the list leaves out any server tool with other characters in its name. When an agent calls a tool you didn't allow, the proxy refuses the call and doesn't send it to the server. The agent gets an error that names the tool, and the call appears in the [session's logs](https://infisical.com/docs/documentation/platform/agent-vault/session-logs.md) as blocked. The proxy also leaves the tools you didn't allow out of the list of tools the server returns to the agent. The proxy picks up a changed list within its [poll interval](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#poll-interval) (60 seconds by default) and refuses calls to the tools you removed from then on. Most agents fetch the list of tools only when they connect, so a running agent shows the new list after you restart it or reconnect the MCP server. To allow every tool again, edit the service and turn on **All Tools**. ## Connect your agent **Step 1** [Create a session](https://infisical.com/docs/documentation/platform/agent-vault/sessions#create-a-session) for the access bundle, and copy the `infisical agent-vault run` command it gives you. **Step 2** Add the MCP server to your agent by its server URL. Don't add a token, and don't sign in to the server from the agent. > [tab] Claude Code > > ```bash theme={"dark"} > claude mcp add --transport http linear https://mcp.linear.app/mcp > ``` > > If the service uses the SSE transport, use `--transport sse` instead. > [tab] Codex > > In `~/.codex/config.toml`, add the server by its URL: > > ```toml theme={"dark"} > [mcp_servers.linear] > url = "https://mcp.linear.app/mcp" > ``` > > Codex connects to remote MCP servers only over Streamable HTTP. If the service uses the SSE transport, use an agent that supports SSE, such as Claude Code. > > Don't use `codex mcp add`, which starts the server's OAuth sign-in from the agent, and don't run `codex mcp login` for the server. > [tab] OpenCode > > In `opencode.json`, add the server as a remote MCP server with OAuth turned off: > > ```json theme={"dark"} > { > "$schema": "https://opencode.ai/config.json", > "mcp": { > "linear": { > "type": "remote", > "url": "https://mcp.linear.app/mcp", > "oauth": false > } > } > } > ``` **Step 3** Start the agent with the command from the session. For example, with Claude Code: ```bash theme={"dark"} infisical agent-vault run --session-token --proxy :17323 -- claude ``` **Step 4** Ask the agent to use one of the server's tools, such as listing your Linear issues. The call appears in the [session's logs](https://infisical.com/docs/documentation/platform/agent-vault/session-logs.md#viewing-session-logs) with the [tool name](https://infisical.com/docs/documentation/platform/agent-vault/session-logs.md#mcp-tool-calls). ## Limitations * **Remote servers only:** An MCP service covers MCP servers that the agent reaches over HTTPS. A local MCP server that the agent starts as a process isn't an MCP service, but you can add [HTTP services](https://infisical.com/docs/documentation/platform/agent-vault/http-apis.md) for the APIs that the local server calls * **No OAuth on private networks:** Infisical connects to the MCP server and to the provider to set up OAuth and refresh the access token, so if either one is on a private network, use a [Bearer token](#bearer-token) instead, or set [`ALLOW_INTERNAL_IP_CONNECTIONS`](https://infisical.com/docs/self-hosting/configuration/envars#param-allow-internal-ip-connections) to `true` if you self-host Infisical on that network * **No connectors that run in a vendor's cloud:** Custom connectors in claude.ai or ChatGPT connect from the vendor's servers, so their traffic never reaches your proxy * **No WebSocket transports:** The proxy doesn't support [WebSocket connections](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#supported-connections) ## Troubleshooting > [accordion] The agent gets a 502 response from the MCP server > > If the server rejects an OAuth service's token, the proxy gets a fresh token from Infisical and sends the request again. If that doesn't work, or if the server rejects a Bearer token, the proxy returns a `502` response to the agent. Its message says what to do: > > **The service needs to be reauthorized:** The provider no longer accepts the service's login, or the server asked for scopes the authorization lacks. The access bundle's **Services** table shows **Needs Reauthorization** or **Missing Scopes** for the service. Open the service's menu, select **Edit**, and continue to the **Credential** step. Select **Reauthorize**, sign in to the provider again, then continue and select **Save**. > > ![The support-triage access bundle in the Customer Support project, listing slack and zendesk as HTTP APIs and linear and notion as MCP servers, with a Needs Reauthorization badge on linear](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/access-bundle-mcp-services.png) > > **Try again in a moment:** The proxy couldn't get a valid token from Infisical this time. Try the tool call again. > > **The service's credential was rejected:** The server rejected the service's Bearer token. Edit the service and paste a new token. > > **The service rejected your credential:** The server rejected the token you set for a [member-provided](#leave-the-credential-to-each-member) service. [Update your personal values](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md#set-up-your-personal-values) for the service. > > **Reconnect your account:** The service is [member provided](#leave-the-credential-to-each-member), and the provider no longer accepts your login, or the server asked for scopes your connection doesn't grant. On the access bundle page, select **Requires Setup** or **Missing Scopes** next to the service, then select **Reconnect**. If the message under your connection says the provider refused the service's OAuth app, reconnecting won't help. Ask a project admin to update the service's OAuth app. > [accordion] Authorize fails on a self-hosted instance > > The redirect URI that Infisical gives the provider is your instance's `SITE_URL` followed by `/agent-vault/oauth/callback`. Check that: > > * `SITE_URL` is set to the URL you use to open Infisical > * `SITE_URL` uses `https://` (providers such as Linear refuse a redirect URI on plain `http://` unless the host is `localhost`) > [accordion] The tools don't load > > If Infisical can't get the server's list of tools, the **Tools** step shows the reason, such as a credential that the server rejected. You can still add tools by typing their names in **Allowed Tools**. > > Infisical can't load the list in these cases: > > * The MCP server is on a private network (if you self-host Infisical on that network, set [`ALLOW_INTERNAL_IP_CONNECTIONS`](https://infisical.com/docs/self-hosting/configuration/envars#param-allow-internal-ip-connections) to `true`) > * The service's credential is [member provided](#leave-the-credential-to-each-member) and you haven't loaded the tools with your own token or sign-in on the **Tools** step > [accordion] The agent asks you to sign in to the MCP server > > The request reached the server without a credential. Check that: > > * The agent runs through `infisical agent-vault run` with a session for the access bundle > * The server URL in the agent has the same host as the service's **Server URL** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.