# 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 sets 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 has 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 an authentication dialog for the server.
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 setting 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