VS Code MCP Server

Let AI agents read, write, debug, and execute commands in VS Code — just like a human developer. This MCP (Model Context Protocol) server exposes 40+ VS Code tools (debugger, terminal, LSP, file ops, commands) over SSE, compatible with opencode, Claude, Cursor, and any MCP client.

Quick Start

1. Install the extension from the VS Code Marketplace or install a .vsix from the latest release.

2. Reload VS Code — the extension starts automatically on startup, listening on http://127.0.0.1:9876.

3. Configure your AI tool (e.g., opencode) to connect via SSE:

   {
     "vscode-mcp": {
       "type": "remote",
       "url": "http://127.0.0.1:9876/mcp"
     }
   }
   

4. Verify the server is running:

   curl -s -X POST http://127.0.0.1:9876/mcp \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

Architecture

VS Code Extension (onStartupFinished)
  └─ src/extension.ts          — Lifecycle: activation, tool registration, deactivation
  └─ src/config.ts             — Settings (port, auth, TLS) from VS Code + env fallbacks
  └─ src/mcp/
       ├─ server.ts            — HTTP server: CORS, auth, TLS, SSE transport, JSON-RPC dispatch
       ├─ transport.ts         — JSON-RPC 2.0 handler + MCP protocol lifecycle (initialize, tools/list, tools/call)
       └─ tools/
            ├─ commands.ts     — Execute any VS Code command, list commands, get code actions
            ├─ navigation.ts   — Open files, line/column jump, select lines, explorer reveal, close editors
            ├─ workspace.ts    — Read/write/create/delete files, glob search, workspace folders
            ├─ debug.ts        — Start/stop debugging, breakpoints (add/remove/list), step/continue,
            │                    stack trace, variables, frame-scoped evaluate
            ├─ terminal.ts     — Execute commands in integrated terminal, capture output (30s timeout)
            └─ lsp.ts          — Diagnostics (200-line cap), hover, references, definitions, symbols,
                                 completions, code actions, call hierarchy, rename
  └─ src/utils/
       ├─ types.ts             — MCP method constants, type definitions
       └─ path.ts              — Workspace-root-aware path resolution

Tools

Connecting from other AI tools

opencode

Add to your opencode.global.jsonc or opencode.json:

{
  "mcpServers": {
    "vscode-mcp": {
      "type": "remote",
      "url": "http://127.0.0.1:9876/mcp"
    }
  }
}

Claude Desktop / Claude Code

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "vscode-mcp": {
      "type": "remote",
      "url": "http://127.0.0.1:9876/mcp"
    }
  }
}

Or via stdio if you prefer a managed subprocess:

{
  "mcpServers": {
    "vscode-mcp": {
      "command": "node",
      "args": ["path/to/vscode-mcp-server/out/cli.js"]
    }
  }
}

Cursor

In Cursor Settings → Features → MCP Servers → Add new MCP server:

Name: vscode-mcp
Type: remote
URL: http://127.0.0.1:9876/mcp

Windsurf / Continue.dev / Any MCP-compatible tool

Add a type: "remote" MCP server pointing to:

http://127.0.0.1:9876/mcp

The server uses SSE transport (the standard MCP HTTP transport). If the tool only supports stdio, you can use an SSE-to-stdio bridge like mcp-remote or write a thin wrapper.

Connecting programmatically

# Example: using the MCP Python SDK
from mcp import ClientSession
from mcp.client.sse import sse_client

async with sse_client("http://127.0.0.1:9876/mcp") as transport:
    async with ClientSession(transport) as session:
        result = await session.list_tools()
        for tool in result.tools:
            print(f"{tool.name}: {tool.description}")

// Example: using the MCP TypeScript SDK
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(new URL("http://127.0.0.1:9876/mcp"));
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const tools = await client.listTools();

With TLS and authentication

Enable TLS and/or auth via VS Code settings or environment variables, then update your client URL and headers accordingly.

Server-side setup:

opencode

{
  "mcpServers": {
    "vscode-mcp": {
      "type": "remote",
      "url": "https://127.0.0.1:9876/mcp",   // https, not http
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Claude Desktop / Claude Code

{
  "mcpServers": {
    "vscode-mcp": {
      "type": "remote",
      "url": "https://127.0.0.1:9876/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Cursor

In Cursor Settings → Features → MCP Servers:

Name: vscode-mcp
Type: remote
URL: https://127.0.0.1:9876/mcp
Headers: { "Authorization": "Bearer <your-token>" }

Programmatic (Python with TLS + auth)

from mcp import ClientSession
from mcp.client.sse import sse_client

async with sse_client(
    "https://127.0.0.1:9876/mcp",
    headers={"Authorization": "Bearer <your-token>"},
) as transport:
    async with ClientSession(transport) as session:
        result = await session.list_tools()

Programmatic (TypeScript with TLS + auth)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("https://127.0.0.1:9876/mcp"),
  { headers: { Authorization: "Bearer <your-token>" } }
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

curl (for testing)

# With TLS
curl -sk https://127.0.0.1:9876/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# With TLS + auth, direct POST
curl -sk -X POST https://127.0.0.1:9876/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

⚠️ Security note: When auth token is set without TLS, the server logs a warning. Bearer tokens over plain HTTP can be intercepted on the local network. Use TLS for any non-loopback access.

Example: tool list (37 tools)

When connected, tools/list returns schemas for all tools. Key categories:

MCP Protocol

Transport

Supports two transport modes:

1. SSE (recommended) — GET /mcp opens an SSE stream, server sends an endpoint event with a session-specific POST URL. Client sends JSON-RPC messages to POST /mcp/session/:id/message, responses arrive via SSE message events.

2. Direct POST (backward compat) — POST /mcp with JSON-RPC body. Synchronous request/response.

Lifecycle

Full MCP protocol lifecycle implemented:

1. Client sends initialize — server responds with protocol version (2024-11-05), capabilities (tools), and server info
2. Client sends notifications/initialized — acknowledges readiness (no response expected)
3. tools/list — returns all tool definitions with JSON schemas
4. tools/call — invokes a tool by name with arguments

Port Retry

If the default port (9876) is busy, the server tries up to 5 consecutive ports (±1 each try). If all fail, the extension logs an error and deactivates.

Configuration

All settings under vscode-mcp-server.*:

Settings fall back to environment variables:

VS Code settings take priority over env vars.

Security

• CORS restricted to loopback origin (Access-Control-Allow-Origin: http://127.0.0.1:<port>)
• Bearer token auth uses timing-safe comparison
• Payload limit: 1 MB
• TLS supported but not required (loopback-only by default)
• Warning logged when auth token is set without TLS

Debug Tips

Frame-Scoped Evaluation

evaluate_in_debug_console automatically resolves the top stack frame's frameId and passes it to the DAP evaluate request. This means you can read local variables directly:

evaluate_in_debug_console("pre")   → 69.75
evaluate_in_debug_console("self")  → Order(order_id='ORD-001', ...)

Without a paused debug session, it falls back to global-scope evaluation.

Debug Workflow

1. Open target file: open_file("src/main.py")
2. Set breakpoints: add_breakpoint("src/main.py", 42)
3. Start debugging: start_debugging("Launch Config Name")
4. Step through: step_over(), step_into(), step_out()
5. Inspect: get_stack_trace(), get_debug_variables(), evaluate_in_debug_console("my_var")
6. Continue: continue()
7. Stop: stop_debugging()

Development

npm install
npm run compile    # Build TypeScript → out/
npm run watch      # Watch mode
npm test           # 75 tests across 3 suites (server, transport, tools)

Debug the extension itself

1. Press F5 in VS Code (uses .vscode/launch.json "Run Extension" config)
2. A new Extension Development Host window opens
3. The MCP server starts automatically on port 9876
4. Set breakpoints in src/ to debug tool handlers
5. The npm: watch task auto-compiles on save

Package for distribution

npx @vscode/vsce package
# Produces vscode-mcp-server-*.vsix

Notes

• Workspace file operations are relative to the first workspace root folder
• Debug tools require an active debug configuration (launch.json) in the workspace
• Terminal tools create integrated terminals in VS Code; output capture has a 30-second timeout to prevent resource leaks
• LSP tools query the active language server; diagnostics are capped at 200 lines with ... and N more suffix
• sourceMap: true is enabled — breakpoints work in the debugger when developing the extension itself