Workspace Bridge MCP

Give your AI client a practical workflow inside VS Code. Read related files together, navigate symbols, prepare precise edits, organize text files, and follow approved command tasks—with access controlled in the editor.

Workspace Bridge is an MCP server inside VS Code. External MCP clients connect to it. VS Code's built-in MCP support goes in the other direction: it makes VS Code a client of other servers. You do not need to add this extension as a server inside VS Code to expose the workspace.

Connection requirement: Streamable HTTP with a custom Authorization: Bearer … header. Bearer authentication is not OAuth; hosted connectors that require OAuth may be incompatible. The bridge does not create a public tunnel.

Real v0.4.0 screenshot in an isolated development profile, with a synthetic demo workspace. No user project, credential or unrelated window is included.

v0.4: edit, review and verify

41 tools now include structured Git, semantic rename, formatting and edit-only quick fixes, plus manifest-bound npm tasks and conservative TAP summaries.

• Preview a bounded multi-file refactor, approve it locally, and apply one text-only WorkspaceEdit. Changes remain unsaved for review. Language features depend on installed providers.

• Inspect Git status, diffs and history; locally approve explicit staging/unstaging and commits bound to a completely reviewed staged patch. No hooks, signing or automatic push. Staging uses raw bytes without clean filters or line-ending conversion.

• Discover root package.json scripts. Approve one run or the same task for this bridge session; changes to the manifest require approval again. Session approval can run changed project code with your account privileges; it is not a sandbox.

• Grant edits, refactors, project tasks, Git writes and arbitrary terminal access separately, for 30 minutes, two hours or this session. Privileged grants expire while read access remains available.

• Run background jobs for up to 60 minutes, sharing three active slots across terminal and project tasks. Retain a bounded rolling log with truncation offsets instead of stopping high-output jobs. Suspected secrets cause output to remain withheld.

Git currently requires a self-contained repository root and repository-local identity for commits; linked worktrees, submodules and special configurations are conservatively restricted. Identity is not returned to the model. Unsupported test output stays unknown. See v0.4 workflows and limits.

Related MCP server: VSCode MCP

One control center, from connection to completion

Open Workspace Bridge: Open Control Center from the Command Palette, the bridge sidebar, or the status bar. See the active workspace and permissions, search the 41-tool directory, follow background tasks, cancel bridge-owned work, and inspect recent request metadata in one editor panel.

The control center supports English and Chinese, keyboard navigation, narrow editor groups, and the active VS Code theme. It never displays tokens, command text, or terminal output. Copy client configuration intentionally copies a token into your clipboard; use it only in a trusted client.

Explore the control center →

Real v0.2.0 screenshot from an isolated VS Code development profile and a synthetic sample project. The native sidebar remains available; this image predates the v0.3 control center. No token or personal project is shown. The banner and workflow illustrations are original project assets.

Start in three steps

1. Install. Download the .vsix from Releases, verify its checksum, then choose Extensions → … → Install from VSIX… in VS Code.

2. Start. Open a trusted folder, open Workspace Bridge in the Activity Bar, and select Open control center → Start bridge. Confirm the workspace shown in the panel.

3. Connect. Select Copy client configuration, add it to a compatible MCP client, then use Copy starter prompt to begin with workspace discovery and reading.

The bridge starts with read access; editing and terminal execution stay off until you enable them locally. Each window has its own token. Connection configuration contains that secret—keep it in protected client settings, out of repositories and chat messages.

Detailed installation, client configuration, and troubleshooting →

Work with the editor's context

The server exposes 41 tools and the review_workspace prompt. v0.3 adds batch reading, wider code navigation, text-file lifecycle tools, and asynchronous command tasks. The tool reference documents exact arguments and limits. Active selection text and background-task output are returned only when explicitly requested.

Permissions you can see

Stopping the bridge or changing workspaces resets editing and terminal grants. Reloading a window creates a new token; rotation revokes the old one immediately. Use the configuration from the intended window and rediscover its workspace before making changes.

Background tasks are session-only: at most three can await approval, run, or stop at once. A task ID or awaiting_approval response is not completion. Poll its state, inspect the final result, and remember that cancellation or failure does not undo effects the command already produced.

Approved terminal commands use your operating-system account; they are not sandboxed. They can access files outside the workspace and use the network.

Connect a client

Copy the actual configuration from the running panel. This example illustrates the connection shape; client schemas differ:

{
  "mcpServers": {
    "workspace-bridge": {
      "type": "http",
      "url": "http://127.0.0.1:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

<PORT> and <TOKEN> are placeholders. A stdio-only client needs its own HTTP adapter. Remote clients need a user-managed HTTPS route; this release has no OAuth authorization server, automatic tunnel, or multi-window router.

Try a first request such as:

Discover the current workspace, then read its README and current diagnostics. Summarize what you found with file references. Do not change files or run terminal commands.

Privacy, with explicit limits

• Local by default. Loopback binding, bearer authentication, VS Code SecretStorage, and no telemetry. Copying the configuration intentionally places a token on the clipboard and in your chosen client.

• Constrained file tools. Relative paths, real-path checks, link rejection, sensitive-name/content filtering, and bounded results. Filters cannot recognize every secret or provide operating-system isolation.

• Minimal bridge records. The control center, activity logs, and exported bridge diagnostics omit file contents, command text, terminal output, tokens, and user absolute paths. Requested file, language-service, and command results still go to the client and follow its retention policies.

Read the security policy, threat model, and audit notes before exposing an endpoint or enabling terminal access. Passing tests and scans do not prove that every vulnerability is absent.

Verification and compatibility

The release workflow checks builds, unit tests, packaging, and privacy on Windows, macOS, and Linux. Real editor integration has also been exercised in isolated Windows and Linux environments. See validation evidence and the CI run for the exact release scope.

Requires VS Code 1.96+. WSL, SSH, containers, and other remote extension hosts need separate acceptance; “local” means the machine running the extension host. Client compatibility depends on transport and authentication support, not the client's brand.

Build and contribute

Requires Node.js 22+:

git clone https://github.com/Yari-tuber/vscode-workspace-bridge-mcp.git
cd vscode-workspace-bridge-mcp
npm ci
npm test
npm run privacy
npm run build
npm run test:integration
npm run package

Integration tests use a separate VS Code profile and temporary workspace. They download a test runtime unless VSCODE_EXECUTABLE selects an existing one. Use dummy data for development and acceptance.

Released under the MIT license. This project does not imply endorsement by VS Code, MCP client vendors, or upstream projects.