---
name: plungeai-in-opencode
description: "Connect OpenCode to PlungeAI (Ocean Studio) over MCP — an opencode.json mcp.plungeai entry with type: remote, {env:VAR} variable substitution for a committed project config, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in OpenCode and says connect / install / set up PlungeAI, mentions opencode.json or the mcp key, or plungeai_* tools aren't responding. 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 OpenCode

OpenCode 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)

Merge into `~/.config/opencode/opencode.json` (user-level — the right home
for the literal key) or the project's `opencode.json`:

    {
      "mcp": {
        "plungeai": {
          "type": "remote",
          "url": "https://mcp.plungeai.com/v1",
          "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
        }
      }
    }

Note the shape: the top-level key is `mcp` (not `mcpServers`), and remote
servers need `"type": "remote"`.

For a committed project `opencode.json`, use OpenCode's variable
substitution so the literal key never lands in the repo:

    "headers": { "Authorization": "Bearer {env:PLUNGEAI_API_KEY}" }

(`{file:path}` substitution also exists for key files.)

## Verify

1. Ask OpenCode: "use plungeai_whoami to confirm my identity" → an identity
   card.
2. Transport-independent check:
   `curl -H "Authorization: Bearer ozk_YOUR_KEY" https://api.plungeai.com/v1/agents`
   → HTTP 200 JSON.
3. "use plungeai_list_agents to search 'web search'" → live results from the
   active agent catalog.

## Quirks

- Project config merges over the user config — if tools behave oddly, check
  whether a committed `opencode.json` (or `.jsonc`) redefines `mcp.plungeai`,
  e.g. with `"enabled": false`.
- `{env:VAR}` resolves at startup: export `PLUNGEAI_API_KEY` before
  launching OpenCode, or the header goes out empty → 401.
- MCP servers connect at startup — restart the OpenCode session after any
  config edit before debugging further.
- OpenCode reads `AGENTS.md` — a discovery-first reminder ("PlungeAI agent
  ids come from a live `plungeai_list_agents` search — never from memory")
  belongs there. It is committed — never put the key in it.
- Money-verb PlungeAI operations still pause with a structured
  `needs_approval` outcome (relay it, then `plungeai_continue`) regardless
  of any approval 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**.