# Connect VS Code (GitHub Copilot)

VS Code with GitHub Copilot connects to remote MCP servers and exposes their
tools to Copilot Chat's **Agent mode**. Add the Zuplo MCP Gateway through a
`.vscode/mcp.json` file in your workspace, the `code` CLI, or the Extensions
view.

## Prerequisites

- A Zuplo MCP Gateway project with at least one Virtual MCP server. See the
  [quickstart](../quickstart.mdx) if you haven't created one yet.
- VS Code installed.
- The GitHub Copilot extension installed and signed in.

## Add the gateway

There are three supported ways to register the gateway.

### Option 1: `.vscode/mcp.json` in your workspace

Create or open `.vscode/mcp.json` at the root of your workspace, then add an
HTTP server entry pointing at the Virtual MCP URL:

```json title=".vscode/mcp.json"
{
  "servers": {
    "zuplo": {
      "type": "http",
      "url": "https://{deploymentUrl}/v1/mcp/{slug}"
    }
  }
}
```

Commit the file to source control to share the configuration with your team.

### Option 2: `code --add-mcp` CLI

Use the VS Code CLI to add a server to your user profile or to a workspace:

```bash
code --add-mcp '{"name":"zuplo","type":"http","url":"https://{deploymentUrl}/v1/mcp/{slug}"}'
```

VS Code prompts you to confirm the server registration and to choose between
user-profile and workspace scope.

### Option 3: Extensions view

1. Open the **Extensions** view in VS Code.
2. Type `@mcp` in the search field. VS Code shows the curated MCP server gallery
   alongside any servers you've already registered.
3. To add a custom server (the Zuplo gateway), use the **MCP: Add Server**
   command from the Command Palette and paste your Virtual MCP URL when
   prompted, or open **MCP: Open User Configuration** to edit `mcp.json`
   directly.

## Authenticate

The first time VS Code talks to the gateway, the gateway returns
`401 Unauthorized` and VS Code opens the OAuth flow in your default browser.

1. Sign in to the gateway with your identity provider.
2. On the gateway's consent page, click **Connect** next to each upstream MCP
   server and complete its OAuth flow.
3. Click **Authorize** to finish. VS Code receives the access token and marks
   the server as connected.

Tokens refresh automatically. To revoke access, remove the server from
`mcp.json` (or from MCP settings) and re-add it to start over.

## Use tools in Copilot Chat

Once the server is connected, open Copilot Chat and switch to **Agent** mode
(the mode picker is at the top of the chat panel). Tools from the gateway appear
in the tool picker — click the tools icon to see them and to enable or disable
individual tools per chat. Reference resources from the gateway by typing `#` in
your prompt.

## What VS Code supports

VS Code's MCP client is one of the most feature-complete on the market. With the
Zuplo MCP Gateway it supports:

- **Tools** — invoke gateway-exposed tools from Agent mode.
- **Prompts** — surface prompts as slash commands.
- **Resources** — reference resources with `#` in prompts.
- **Roots** — declare workspace folders as roots.
- **Sampling** — handle server-initiated sampling requests, including the
  `tools` and `toolChoice` parameters added in MCP `2025-11-25`.
- **Elicitation** — handle both form-mode and URL-mode elicitation requests,
  including upstream re-authorization prompts.
- **MCP Apps** — render interactive HTML widgets inline in the chat.
- **DCR** and **CIMD** — both client registration paths are supported.

## Troubleshooting

- **Server stays in "Pending" state.** Confirm the URL in `mcp.json` is
  reachable. VS Code shows server logs in the **Output** panel under **MCP** —
  check there for the exact failure reason.
- **Tools do not appear in Copilot Chat.** Confirm Copilot Chat is in **Agent**
  mode. Tool calling is gated to that mode.
- **OAuth flow does not start.** Some corporate proxies block the local
  callback. Try connecting from outside the proxy or use the VS Code setting to
  override the callback port.

## Related

- [Connect MCP clients overview](./overview.mdx)
- VS Code's docs:
  [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
- [Authentication overview](../auth/overview.mdx)