plungeai-in-opencode

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.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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 (opens in a new tab)) — 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

Ask OpenCode: "use plungeai_whoami to confirm my identity" → an identity card.
Transport-independent check: curl -H "Authorization: Bearer ozk_YOUR_KEY" https://api.plungeai.com/v1/agents → HTTP 200 JSON.
"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.
Full guide: https://mcp.plungeai.com/docs#3-connecting-clients (opens in a new tab)