Connect VS Code to a gateway

VS Code reaches an MCP gateway 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.

With an API key

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

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

For a gateway with OAuth on, the entry carries the client ID that the person managing your identity provider registered for VS Code, and no header:

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

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

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

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, in the Reason column of the auth-failed event, next to the person's name.

See also

Learn more