---
name: plungeai-in-vscode
description: "Connect VS Code (GitHub Copilot agent mode) to PlungeAI (Ocean Studio) over MCP — the code --add-mcp CLI command, a committed-safe .vscode/mcp.json with an input-prompted key, the 128-tools-per-request cap, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in VS Code/Copilot and says connect / install / set up PlungeAI, mentions mcp.json or code --add-mcp, or plungeai_* tools aren't appearing in agent mode. For another editor use its plungeai-in-<tool> skill; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config."
---

# PlungeAI in VS Code (GitHub Copilot agent mode)

VS Code talks to PlungeAI over the Streamable HTTP MCP server at
`https://mcp.plungeai.com/v1`. One `ozk_` bearer key authenticates it (and
the One API, if generated code calls PlungeAI directly).

## Prerequisites

- An `ozk_` key: Dashboard → **One API → Keys** (https://dashboard.plungeai.com) —
  self-service, shown once, copy it now.

## Connect (once)

### From a terminal (simplest working path)

    code --add-mcp '{"name":"plungeai","type":"http","url":"https://mcp.plungeai.com/v1","headers":{"Authorization":"Bearer ozk_YOUR_KEY"}}'

(PowerShell/cmd: double-quote the JSON and escape inner quotes with `\"`.)

### By hand — the committed-safe pattern

`.vscode/mcp.json` in the workspace. The `inputs` block makes VS Code prompt
for the key once and store it encrypted — the file never holds the key, so
it is safe to commit:

    {
      "inputs": [
        {
          "id": "plungeai-key",
          "type": "promptString",
          "password": true,
          "description": "PlungeAI ozk_ key"
        }
      ],
      "servers": {
        "plungeai": {
          "type": "http",
          "url": "https://mcp.plungeai.com/v1",
          "headers": { "Authorization": "Bearer ${input:plungeai-key}" }
        }
      }
    }

Machine-wide instead: **MCP: Open User Configuration** (the `mcp.json` in
your user profile), or **MCP: Add Server** → choose the user scope — same
fields, outside any repo.

The install page's "Add to VS Code" button emits one URL-encoded JSON
object (`vscode:mcp/install?{"name":"plungeai","type":"http","url":…}`) —
matching VS Code's documented deeplink shape. If it ever fails to parse,
`code --add-mcp` or the file above works unconditionally.

## Verify

1. **MCP: List Servers** shows `plungeai` running; the Tools picker lists
   `plungeai_*`.
2. In Copilot agent chat: "use plungeai_whoami to confirm my identity" → an
   identity card.
3. "use plungeai_list_agents to search 'web search'" → live results from the
   active agent catalog.

## Quirks

- MCP tools run in **agent mode** (Chat view → mode picker → Agent). The
  `plungeai_*` tools appear in the chat Tools picker once the server starts.
- **128 tools max per chat request**, across all sources. Over the limit:
  deselect other servers/tools in the Tools picker, or rely on virtual tools
  — `github.copilot.chat.virtualTools.threshold` auto-groups tools beyond
  the threshold and lets the model expand a group on demand.
- Mistyped key: **MCP: List Servers** → `plungeai` → **Show Output** shows
  the 401. Restart the server from the same menu; if it doesn't re-prompt
  for the stored input, remove and re-add the server.
- Locked-down setups: `chat.mcp.access` governs which MCP servers can be
  used; org policies (`ChatAllowedMcpServers` / `ChatDeniedMcpServers` /
  `ChatAllowManagedMcpServersOnly`) allow- or deny-list servers — a missing
  MCP section in settings usually means one of these.
- Trust: VS Code asks you to confirm you trust the server before first
  start — except when it's started directly from `mcp.json`.
- Money-verb PlungeAI operations still pause with a structured
  `needs_approval` outcome (relay it, then `plungeai_continue`) regardless
  of any trust/confirmation setting.

## Where next

- Operating the `plungeai_*` tools once connected: **plungeai-mcp-setup**.
- Writing code that calls `https://api.plungeai.com` directly: **plungeai-api-setup**.
- Picking MCP vs the One API for a given job: **choose-your-plungeai-door**.
- An unlisted but MCP-capable client, or the shared connect concepts (native
  remote vs. stdio bridge, key hygiene): **plungeai-mcp-setup**.