Pylon — VS Code MCP Server

Exposes VS Code terminals and IDE features to AI coding agents (Claude Code, Gemini, Cursor, etc.) via a local MCP server. Supports multiple VS Code windows simultaneously through a hub/satellite session model.

Zero dependencies. No proxy. One HTTP endpoint.

Architecture

AI Agent (Claude Code / Gemini / any MCP client)
         │  HTTP POST /mcp
         ▼
   Hub (port 27681)  ◄── session registry
         │
         │  HTTP forward (session_id routing)
         ▼
   AgentServer A (port 27691)   ← Window A
   AgentServer B (port 27692)   ← Window B
   AgentServer C (port 27693)   ← Window C

Every VS Code window runs its own internal AgentServer (port 27691+). The first window to open also starts the Hub on port 27681 — the single MCP endpoint. Subsequent windows register as satellites and send heartbeats. If the hub closes, a satellite auto-promotes.

Installation

1. Build & install the extension

npm run compile
npm install -g @vscode/vsce
vsce package
code --install-extension pylon-0.2.0.vsix

2. Add MCP config to your AI agent

The MCP endpoint is always http://127.0.0.1:27681/mcp.

Claude Code (~/.claude.json or via CLI):

{
  "mcpServers": {
    "pylon": {
      "type": "http",
      "url": "http://127.0.0.1:27681/mcp"
    }
  }
}

claude mcp add --transport http pylon http://127.0.0.1:27681/mcp

Gemini / other agents: use the same URL in their respective MCP config.

3. That's it

The extension auto-starts when VS Code opens. The status bar shows the current role:

• ⬡ Pylon Hub: myproject — this window owns the hub
• ◎ Pylon: myproject — satellite connected to hub

Available Tools

Terminal Tools

IDE Tools

Editor Tools

Debug Tools

All tools accept an optional session_id parameter to target a specific VS Code window.

Diagnostics Example

Agent calls: get_diagnostics(severity="error", session_id="frontend")
→ 3 diagnostic(s):
→
→ src/app.ts:42:5 Error [ts]: Property 'foo' does not exist on type 'Bar'.
→ src/utils.ts:10:12 Error [ts]: Cannot find name 'response'.
→ src/index.ts:3:1 Error [eslint]: 'React' must be in scope when using JSX.

No need to run tsc or eslint manually — diagnostics come directly from VS Code's language services in real time.

Multi-Window / Multi-Agent Usage

Each VS Code workspace is automatically identified by its folder name as a session ID.

An AI agent should call terminal_list_sessions at the start of a conversation to discover available sessions, identify its own workspace, and use that session_id for all subsequent calls. The tool descriptions instruct agents to do this automatically — no manual configuration required.

Example flow:

Agent calls: terminal_list_sessions
→ [hub]       session="frontend"  agent=http://127.0.0.1:27691
→ [satellite] session="backend"   agent=http://127.0.0.1:27692

Agent in "backend" workspace then uses:
  terminal_run(command="npm run dev", session_id="backend")
  terminal_read_output(session_id="backend", lines=50)
  get_diagnostics(session_id="backend", severity="error")

Hub Failover

If the hub window closes:

1. Satellites detect the missing heartbeat within ~5 seconds
2. The first satellite to respond claims port 27681 and becomes the new hub
3. Other satellites re-register with the new hub automatically

Shell Integration Setup

terminal_run requires VS Code shell integration to be active. Shell integration provides command boundary tracking and output capture via OSC 633 sequences.

Check status: Command Palette → Pylon: Diagnose Shell Integration Shows shellIntegration=YES/NO and cwd for each terminal. If cwd=undefined despite YES, the shell isn't sourcing the integration script.

Per-shell setup

PowerShell — works automatically, no setup needed.

WSL / bash — add to ~/.bashrc:

. "$(code --locate-shell-integration-path bash)"

zsh — add to ~/.zshrc:

. "$(code --locate-shell-integration-path zsh)"

fish — add to ~/.config/fish/config.fish:

source (code --locate-shell-integration-path fish)

CMD — not supported natively. Install Clink for CMD shell integration support.

After adding the script, close and reopen the terminal. Run the diagnose command to confirm cwd is no longer undefined.

If PowerShell blocks profile scripts

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Output Buffering

Terminal output is buffered via VS Code's shell integration events (onDidStartTerminalShellExecution). Shell integration is required for buffering — terminals without it will show no buffered output.

terminal_run executes a command and returns its output inline. terminal_read_output reads the accumulated buffer from all previous commands in that terminal session.

Settings

Ports

Tool Access Control

Control which tools AI agents can use. All tools are enabled by default.

Visual picker: Command Palette → Pylon: Configure Tool Access — multi-select grouped by category (Terminal, IDE, Editor, Debug).

Manual: Add tool names to pylon.disabledTools in settings:

{
  "pylon.disabledTools": ["debug_start", "rename_symbol", "run_command"]
}

Disabled tools are hidden from tools/list and rejected on tools/call. Changes take effect immediately on the next agent request.

Security

• All servers bind to 127.0.0.1 only — no network exposure
• No authentication — intended for local development use only
• Request bodies capped at 1 MB