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, such as Linear’s or Notion’s, during a session. It’s one of the two types of service 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 attaches the service’s credential, so the agent can call the server’s tools without ever holding the credential.

​

Prerequisites

• The Admin role in your Agent Vault project
• An access bundle to add the MCP server to
• A running proxy that your agent can reach
• An account with the MCP server’s provider, or a token the server accepts

​

Add an MCP server

1. In your Agent Vault project, go to Access Bundles. Select your access bundle, then select Add Service.

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.

   
3. On the Details step, enter a Name, and check the Transport and Server URL. A template fills in the transport and server URL for you. Select Continue.

   
4. On the Credential step, pick a Credential Type and set up the credential. Select Continue.

   
5. On the Tools step, choose which of the server’s tools agents can call. Select Continue.

   
6. On the Review step, select Add Service. The service appears in the bundle’s list with the type MCP Server.

   

Next, 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.

​

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 when the access token expires or the server rejects it. The proxy only receives the access token, and the agent never receives any token.

1. Under Credential Type, select OAuth, then select Authorize.

   

   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.

2. In the pop-up window, sign in to the provider and approve access.

3. When Infisical shows Authorized and the scopes the provider granted, select Continue. Continue stays disabled until the authorization succeeds.

   

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.

​

Bearer token

With a Bearer token, you paste a token the MCP server accepts into Token, such as a GitHub personal access token for GitHub MCP. The proxy sends the token as Authorization: Bearer <token>.

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.

​

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 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, 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:

1. Create an OAuth app with the provider, and set its redirect URI to the Redirect URI that Infisical shows.

2. Enter the app’s Client ID and Client Secret on the Credential step.

3. Continue to the Review step, then select Add Service again, or Save if you’re editing the service.

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.

1. On the Credential step, expand Advanced Options and select Add Custom Header.

2. Enter the header’s Name, an optional Prefix, and the Value. To use a variable, 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.

1. On the Tools step, turn off All Tools.

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, 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.

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 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 (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

1. Create a session for the access bundle, and copy the infisical agent-vault run command it gives you.

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.

   Claude Code

   claude mcp add --transport http linear https://mcp.linear.app/mcp
   

   If the service uses the SSE transport, use --transport sse instead.

   Codex

   In ~/.codex/config.toml, add the server by its URL:

   [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.

   OpenCode

   In opencode.json, add the server as a remote MCP server with OAuth turned off:

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "linear": {
         "type": "remote",
         "url": "https://mcp.linear.app/mcp",
         "oauth": false
       }
     }
   }
   
3. Start the agent with the command from the session. For example, with Claude Code:

   infisical agent-vault run --session-token <session-token> --proxy <proxy-host>:17323 -- claude
   
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 with the tool name.

​

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 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 instead, or set 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

​

Troubleshooting

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.

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 service. Update your personal values for the service.

Reconnect your account: The service is member provided, 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.

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)

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 to true)
• The service’s credential is member provided and you haven’t loaded the tools with your own token or sign-in on the Tools step

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