Connect MCP Servers from Your IDE

​

Why use the TrueFoundry Gateway

• Observability — every tool call is logged and traceable to the developer who made it.
• Governance — access is controlled by TrueFoundry identity and server-level permissions; admins decide who can reach which servers.
• Security — no API keys or provider tokens are stored in IDE config files, shell history, or anywhere on the developer machine. The developer signs in with TrueFoundry (using SSO if configured) and the Gateway handles the rest.

​

How the connection flow works

• The developer only interacts with TrueFoundry sign-in (steps 2–3). No keys to copy or paste.
• Provider tokens are stored at the Gateway layer (step 7), not on the developer machine.
• Every subsequent tool call (step 8) goes through the Gateway, where it is logged, authorized, and rate-limited.

​

Prerequisites

• An MCP server registered in TrueFoundry that you have access to. If you don’t have one yet, see Getting Started.
• A Gateway URL for the MCP server. Copy it from the server’s How To Use tab in TrueFoundry.
• For outbound auth — only if the server uses “your own API key” (per-user): your own upstream API key for that provider. You will be prompted to enter it during the connection flow from your IDE. Other outbound methods (shared key, OAuth, token passthrough, no auth) need no key from you.

​

Connect the server

1

Add the server in your IDE

Open the MCP server page in TrueFoundry. Click Add to Client or go to the How To Use tab to see the Gateway URL and connection instructions for your IDE.

Follow the instructions shown for your IDE, or configure it manually below. You only need the Gateway URL — no token in the config.

• Cursor
• Claude Code
• VS Code

Add the server to your mcp.json:

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

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

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

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"
    }
  }
}

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:

Add the Gateway URL to .vscode/mcp.json in your workspace:

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

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

2

Sign in and approve the access request

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.

3

Authorize access to the upstream provider (if needed)

After signing in with TrueFoundry, the Gateway checks how the MCP server authenticates with its upstream provider. What happens next depends on the outbound authentication method configured for the server:

Outbound method	What happens
Shared key	Nothing — the admin has already configured a shared key for the server. You go straight to your IDE.
Client credentials	Nothing — the Gateway exchanges credentials with the provider automatically.
Token passthrough	Nothing — the Gateway forwards your TrueFoundry token to the provider.
No auth	Nothing — the provider does not require authentication.
OAuth (per-user)	The provider’s authorization screen opens (for example, GitHub or Slack). Sign in with your own account and approve access. This is a one-time step — skipped on future connections if you have already authorized this provider.
Your own API key (per-user)	You are prompted to enter your upstream API key for the provider. This is also a one-time step.

For OAuth (per-user), the provider’s authorization screen looks like this:

For Your own API key (per-user), the prompt looks like this:

A virtual MCP server bundles tools from several servers, so you may see more than one authorization prompt — for example, an OAuth screen for one provider and an API key prompt for another.

4

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.

5

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.

​

FAQ and troubleshooting

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

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

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

{
  "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}"
      }
    }
  }
}

{
  "server-name": {
    "Authorization": "Bearer <your-server-token>",
    "X-Custom-Header": "value"
  }
}

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

claude mcp add --transport http github https://<gateway>/<tenant>/mcp/github/server \
  --header "x-tfy-mcp-headers: {\"github\":{\"Authorization\":\"Bearer <your-server-token>\"}}"

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mcp-server-token",
      "description": "Token for the MCP server",
      "password": true
    }
  ],
  "servers": {
    "github": {
      "type": "http",
      "url": "https://<gateway>/<tenant>/mcp/github/server",
      "headers": {
        "x-tfy-mcp-headers": "{\"github\":{\"Authorization\":\"Bearer ${input:mcp-server-token}\"}}"
      }
    }
  }
}