Connect MCP Servers from Your IDE

You can connect to MCP servers on the TrueFoundry MCP Gateway directly from your IDE. Add the server’s Gateway URL in your IDE, authenticate with Gateway, and start using the server’s tools.

Two ways to authenticate

Each IDE supports two ways to authenticate to the Gateway. Pick whichever fits your setup — each IDE guide below shows both.

Method	What you add to your IDE	When to use
Sign in with TrueFoundry	Just the Gateway URL — no token	The simplest option. Your IDE opens the browser the first time and you sign in with TrueFoundry (using SSO if configured). No need to manage API key or token.
API key in headers	The Gateway URL plus an `Authorization` header with a TrueFoundry API key	When you prefer a static token, or your platform version doesn’t offer the browser sign-in flow.

These map to the TrueFoundry OAuth and TrueFoundry API Key (PAT) inbound methods in Authentication and Security.

Prerequisites

An MCP server registered in TrueFoundry that you have access to. If you don’t have one yet, see Getting Started.
For inbound auth — only if you use the token-in-headers method: a token to authenticate to the Gateway. This can be a TrueFoundry API key (PAT), a Virtual Account token, or a JWT from your own Identity Provider. Not needed if you sign in with TrueFoundry.
For outbound auth — only if the server uses “your own API key” (per-user): your own upstream API key for that provider, supplied once through Auth Overrides or when prompted during connection. Other outbound methods (shared key, OAuth, token passthrough, no auth) need no key from you.

The examples below use the tenant-scoped URL form https://<gateway>/<tenant>/mcp/<server>/server. Always copy the exact URL shown on the How To Use tab for your server — that is the source of truth.

Connect the server

Adding the server differs per tool, but every step after that is the same. Follow the steps below in order.

Add the server in your IDE

Pick your tool below and add the server using either way to authenticate: sign in with TrueFoundry (no token), or provide a TrueFoundry API key in the headers.

Cursor
Claude Code
VS Code

Sign in with TrueFoundry (no token)
API key in headers

Add only the Gateway URL — no token in the config.

Use the one-click button (recommended)

From the MCP server’s How To Use tab in TrueFoundry, click Add MCP to Cursor to add the configuration to Cursor automatically.

The How To Use tab in TrueFoundry showing the Cursor configuration and the Add MCP to Cursor button

Or configure it manually

Add the server to your mcp.json:

{
  "mcpServers": {
    "github": {
      "url": "https://<gateway>/<tenant>/mcp/github/server"
    }
  }
}

Add the Gateway URL plus an Authorization header with your TrueFoundry API key:

{
  "mcpServers": {
    "github": {
      "url": "https://<gateway>/<tenant>/mcp/github/server",
      "headers": {
        "Authorization": "Bearer <your-tfy-api-key>"
      }
    }
  }
}

Treat the API key like a password. Avoid committing mcp.json with a real token to version control.

After adding it, Cursor prompts you to install the server:

Cursor's Install MCP Server dialog showing the server name, type, and Gateway URL

Once installed, the server shows as needing authentication until you sign in:

An MCP server entry labeled github-remote showing Needs authentication and a Connect button

Sign in with TrueFoundry (no token)
API key in headers

Add only the Gateway URL — no token in the config.Add the server with the Claude Code CLI:

claude mcp add --transport http github https://<gateway>/<tenant>/mcp/github/server

Or add it to your project’s .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://<gateway>/<tenant>/mcp/github/server"
    }
  }
}

Add the Gateway URL plus an Authorization header with your TrueFoundry API key.With the Claude Code CLI:

claude mcp add --transport http github https://<gateway>/<tenant>/mcp/github/server \
  --header "Authorization: Bearer <your-tfy-api-key>"

Or in your project’s .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://<gateway>/<tenant>/mcp/github/server",
      "headers": {
        "Authorization": "Bearer <your-tfy-api-key>"
      }
    }
  }
}

Treat the API key like a password. Avoid committing .mcp.json with a real token to version control.

For an enterprise, MDM-managed Claude Code setup that pre-seeds gateway-backed MCP servers across machines, see Enterprise Security with MDM.

After adding it, Claude Code shows the server with a sign-in prompt:

Claude Code showing the github-remote MCP server with status needs authentication and an Authenticate option

Sign in with TrueFoundry (no token)
API key in headers

Add only the Gateway URL to .vscode/mcp.json in your workspace — no token in the config:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://<gateway>/<tenant>/mcp/github/server"
    }
  }
}

Add the Gateway URL plus an Authorization header with your TrueFoundry API key. Use an input so the token isn’t stored in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tfy-api-key",
      "description": "TrueFoundry API key",
      "password": true
    }
  ],
  "servers": {
    "github": {
      "type": "http",
      "url": "https://<gateway>/<tenant>/mcp/github/server",
      "headers": {
        "Authorization": "Bearer ${input:tfy-api-key}"
      }
    }
  }
}

Treat the API key like a password. Use an input (as above) rather than hardcoding the token, and avoid committing a real token to version control.

Once added, VS Code prompts you to authenticate to the Gateway:

VS Code showing the .vscode/mcp.json with the server added and a prompt asking to authenticate to the MCP Gateway, with Allow and Cancel

The first time you use the server, your IDE opens the browser to TrueFoundry. Sign in (using SSO if your organization has it configured), then review what’s requesting access — your IDE and the MCP Gateway URL it’s connecting to — and click Approve.

If you added an API key in the headers instead of just the Gateway URL, the token authenticates you — so this browser sign-in and approval don’t happen.

The TrueFoundry consent screen titled Connect via Truefoundry Gateway, showing the Gateway URL, redirect URL, and an Approve button

Complete the server's outbound authentication (if needed)

What you see here depends on the server’s outbound authentication. Most models — shared keys, token passthrough, client credentials, no auth — need no action, since the Gateway handles them automatically. Two need a one-time action from you:

OAuth (per-user)
Your own API key (per-user)

The provider’s own authorization screen (for example, GitHub or Slack) opens for you to sign in and authorize access with your own account. Skipped if you’ve already authorized this provider.

The Sentry authorization screen showing the MCP client requesting access, with selectable tool scopes and an Approve button

A virtual MCP server bundles tools from several servers, so you may complete more than one of the actions above — for example, authorize one provider via OAuth and provide your own key for another.

Return to your IDE

After you approve, the browser redirects automatically back to your IDE — there’s no confirmation page to act on. You can close the browser tab.

The browser redirect page showing the server as Connected and a Redirect Now button back to the IDE

Use the connected tools

Back in your IDE, the server now shows as connected and its tools are listed. You can use them from your agent.

Troubleshooting

You're asked to sign in again

You accidentally denied access

If you declined the access request or closed the browser before finishing, trigger the connection again from your IDE and approve it this time.

The connection stopped working

If the server’s tools stop responding, reconnect from your IDE to sign in again. If the server uses a third-party provider, you may also need to authorize that provider again. Confirm you still have access to the server in TrueFoundry under the server’s Collaborators.

​Two ways to authenticate

​Prerequisites

​Connect the server

​Troubleshooting

Two ways to authenticate

Prerequisites

Connect the server

Troubleshooting