# Connect VS Code to a gateway

Add an MCP gateway to VS Code with an API key or with a sign-in through your identity provider.

VS Code reaches an [MCP gateway](https://zato.io/docs/ai/mcp/index.html) through an entry in `.vscode/mcp.json` in the workspace, or in the user-level file that **MCP: Open User Configuration** opens, and the gateway's tools then appear in the agent mode of Copilot Chat. The entry has two forms, and which one you write depends on how the gateway is [secured](https://zato.io/docs/ai/mcp/security.html).

## With an API key {#with-an-api-key}

For a gateway secured with an API key or a static bearer token, the entry carries the header:

```json
{
    "servers": {
        "billing": {
            "type": "http",
            "url": "https://api.example.com/mcp/billing",
            "headers": {"X-API-Key": "the-actual-key"}
        }
    }
}
```

To keep the key out of the file, declare it under `inputs` and reference it as `${input:billing-key}` in the header - VS Code asks for the value once and stores it.

## With OAuth {#with-oauth}

For a gateway with [OAuth](https://zato.io/docs/ai/mcp/oauth.html) on, the entry carries the client ID that the person managing your identity provider registered for VS Code, and no header:

```json
{
    "servers": {
        "billing": {
            "type": "http",
            "url": "https://api.example.com/mcp/billing",
            "oauth": {
                "clientId": "<client-id>"
            }
        }
    }
}
```

Without the `oauth` block, VS Code tries to register itself with the provider, which works with Keycloak when dynamic registration is on and never with Entra ID.

## What the identity provider needs {#what-the-identity-provider-needs}

The registration for VS Code is a public client with these redirect URIs:

- `http://127.0.0.1:33418/` - the local address VS Code listens on during the sign-in
- `https://vscode.dev/redirect` - the hosted address it uses when the local one is not reachable

VS Code asks for a token for the gateway's URL, so with Entra ID the registration also needs the API's scope among its permissions - the steps are on the [OAuth](https://zato.io/docs/ai/mcp/oauth.html#microsoft-entra-id) page.

## The sign-in {#the-sign-in}

1. After the entry is saved, the server appears in the **MCP Servers** view of the Extensions panel. Starting it, or opening the first chat that uses its tools, makes VS Code show a dialog that the server wants to authenticate.
2. Allowing it opens the browser at your identity provider's sign-in page.
3. After the sign-in, the browser returns to VS Code and the server's tools are listed.

VS Code keeps the account under **Accounts** in the activity bar, where the server can be signed out of, and refreshes the token on its own until the provider's session ends.

## When access is refused {#when-access-is-refused}

A person whose token the gateway does not accept - outside the group the gateway's bearer definition lists, or signed in to the wrong tenant - sees the server fail to start in the **MCP Servers** view with a 401 in its output, and VS Code offers the sign-in again. The reason is in the gateway's [audit log](https://zato.io/docs/ai/mcp/audit-log.html), in the **Reason** column of the `auth-failed` event, next to the person's name.

## See also {#see-also}

- [OAuth](https://zato.io/docs/ai/mcp/oauth.html) - How the sign-in works and how to set up Entra ID or Keycloak
- [Sharing with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) - The export with the gateway's address and the other clients' snippets
- [MCP gateways](https://zato.io/docs/ai/mcp/index.html) - Configuration and the governance controls

## Learn more {#learn-more}

- [MCP tutorial](https://zato.io/tutorials/mcp/01.html) - Expose Python services as AI tools and connect Claude Code in minutes
- [AI Integrations overview](https://zato.io/docs/ai/) - Both directions of AI traffic in one platform, and where to start
- [MCP gateway reference](https://zato.io/docs/ai/mcp/) - Configuration, endpoint behavior and the governance controls
- [Tool schemas](https://zato.io/docs/ai/mcp/tool-schemas.html) - How a service's docstring and declared I/O become its tool definition
- [MCP gateway security](https://zato.io/docs/ai/mcp/security.html) - API keys, Basic Auth and bearer tokens for AI agents
- [MCP response controls](https://zato.io/docs/ai/mcp/response-controls.html) - PII removal, prompt-injection safeguards and token-denominated size caps
- [MCP audit log](https://zato.io/docs/ai/mcp/audit-log.html) - What each agent did, when and with what outcome - payloads never recorded
- [MCP alerts](https://zato.io/docs/ai/mcp/alerts.html) - Failing backends, agents stuck in a loop and gateways with too many tools
- [Cost and limits](https://zato.io/docs/ai/cost-and-limits.html) - Every knob that caps AI cost and traffic, with worked examples
- [GitOps for AI integrations](https://zato.io/docs/ai/enmasse.html) - LLM connections and MCP gateways as YAML in version control
- [AI examples](https://zato.io/docs/ai/examples/) - Complete, runnable scenarios - one real-world need per file