Portal

English · 简体中文

Portal is a VS Code extension that exposes the current workspace as a public MCP endpoint. It is deliberately small: commands and file transfer only.

Connect any MCP client (Claude, ChatGPT, Cursor, a custom agent, curl) to your machine over a tunnel. The agent can run shells and move files. It cannot edit text through MCP tools — there are none.

What you get

Related MCP server: local-bridge

MCP tools (exactly five)

Shells: powershell (Windows default), pwsh, cmd, bash / sh (Git Bash when present). UTF-8 is set up automatically.

Session: reuse the Mcp-Session-Id from initialize. If it is lost or rejected, initialize again — do not invent an ID.

There are no read_file / write_file / edit_file / list_* / search_files tools. Read and write with the shell or the HTTP file API.

File transfer (bidirectional HTTP)

Same tunnel and token as MCP. Default max size: 64 MiB (portal.maxTransferBytes). Uploads replace atomically. Downloads support Range and return SHA-256.

GET    {base}?op=info              capability + workspace
GET    {base}?glob=**/*            list files
GET    {base}/<relpath>            download
HEAD   {base}/<relpath>            metadata
PUT    {base}/<relpath>            upload
DELETE {base}/<relpath>            delete
POST   {base}?op=pack              zip  JSON { "paths": ["src"] }
POST   {base}?op=unpack&dest=.     unzip (raw zip body)

Free ngrok domains need the header ngrok-skip-browser-warning: 1.

# download
curl -fsSL -H "ngrok-skip-browser-warning: 1" \
  "$BASE/README.md" -o README.md

# upload
curl -fsSL -H "ngrok-skip-browser-warning: 1" \
  -T ./photo.png "$BASE/incoming/photo.png"

# pack a folder
curl -fsSL -H "ngrok-skip-browser-warning: 1" \
  -H "Content-Type: application/json" \
  -d '{"paths":["src"]}' "$BASE?op=pack" -o src.zip

Tunnel providers

Route token is the secret path segment. MCP lives at /mcp/<token>. Leave portal.routeToken empty to generate one on start.

Commands (palette)

• Portal: Start / Stop

• Portal: Copy URL

• Portal: Check Tunnel

• Portal: Settings

• Portal: Install cloudflared / Install/Upgrade ngrok

• Portal: Show Log / Show Agent Terminal

Useful settings: portal.startOnActivation (default on), portal.showCommandsInTerminal, portal.localPort (0 = auto, except named Cloudflare).

Build

Requires Node 18+ and VS Code ^1.95.0.

npm install
npm run build      # esbuild → dist/extension.js
npm run typecheck
npm run package    # .vsix (no bundled node_modules)

Load the packaged VSIX, or run the extension in a desktop VS Code host (extensionKind: ui + workspace).

License

MIT