# Connect PlungeAI

You are an AI agent setting up PlungeAI for your user. Follow the steps in order and stop to ask the user whenever a step needs something only they have.

## What PlungeAI is

PlungeAI has two front doors that take the same `ozk_` key. The MCP server at `https://mcp.plungeai.com/v1` gives any MCP client 20 `plungeai_*` tools; the One API at `https://api.plungeai.com` is the REST surface with seven planes (models, tools, agents, workflows, MCP, discovery and traces).

## Step 1: get a key

Ask the user for an `ozk_` key from Dashboard → One API → Keys (https://dashboard.plungeai.com/one-api?tab=keys). The key is shown once when it is created. Have the user export it in the shell you run in:

```bash
export PLUNGE_API_KEY=ozk_...
```

Never write the key into a file inside a repository. Keep it in the shell, or in a user-level client config file outside every repository.

## Step 2: detect the client and connect

Find out which client you are running in, then use the one entry for it. Every entry connects to `https://mcp.plungeai.com/v1`.

### Claude Code

```bash
claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 --header "Authorization: Bearer $PLUNGE_API_KEY" --scope user
```

`--scope user` keeps the entry in `~/.claude.json`, outside the repository.

### Codex

```bash
export PLUNGEAI_API_KEY="$PLUNGE_API_KEY"
codex mcp add plungeai --url https://mcp.plungeai.com/v1 --bearer-token-env-var PLUNGEAI_API_KEY
```

Codex reads the key from `PLUNGEAI_API_KEY` each time it starts, so the export must be in the shell that launches Codex.

### Cursor

Merge into `~/.cursor/mcp.json` (user-level):

```json
{
  "mcpServers": {
    "plungeai": {
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ${env:PLUNGE_API_KEY}" }
    }
  }
}
```

Then toggle the server off and on in Settings → MCP.

### VS Code

```bash
code --add-mcp "{\"name\":\"plungeai\",\"type\":\"http\",\"url\":\"https://mcp.plungeai.com/v1\",\"headers\":{\"Authorization\":\"Bearer $PLUNGE_API_KEY\"}}"
```

MCP tools run in Copilot agent mode.

### Gemini CLI

Merge into `~/.gemini/settings.json` (user-level). Write the value of `PLUNGE_API_KEY` where the entry says `<value of PLUNGE_API_KEY>`; this file is outside every repository, so the literal key may live there:

```json
{
  "mcpServers": {
    "plungeai": {
      "httpUrl": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer <value of PLUNGE_API_KEY>" }
    }
  }
}
```

The key is `httpUrl`, not `url`. Run `/mcp reload` after the edit.

### OpenCode

Merge into `~/.config/opencode/opencode.json` (user-level):

```json
{
  "mcp": {
    "plungeai": {
      "type": "remote",
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer {env:PLUNGE_API_KEY}" }
    }
  }
}
```

Export `PLUNGE_API_KEY` before OpenCode starts, then restart the session.

### Windsurf

Merge into `~/.codeium/windsurf/mcp_config.json` (user-level), writing the value of `PLUNGE_API_KEY` in place of `<value of PLUNGE_API_KEY>`:

```json
{
  "mcpServers": {
    "plungeai": {
      "serverUrl": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer <value of PLUNGE_API_KEY>" }
    }
  }
}
```

Refresh the MCP servers in the Cascade MCP panel after the edit.

These docs use PLUNGE_API_KEY; the PlungeAI skills, the Claude Code plugin and the install page use PLUNGEAI_API_KEY; any name works if your config and shell agree.

## Step 3: verify

Call the `plungeai_whoami` tool. It returns the user, the auth type and tier, the key label and the current rate-limit window. A 401 means the key is missing, mistyped, revoked or expired: ask the user for the key again.

## Step 4: skills

Skills teach you PlungeAI's conventions. Download `https://mcp.plungeai.com/skill.zip`, or one zip per skill from `https://skills.plungeai.com` (for example `https://skills.plungeai.com/choose-your-plungeai-door.zip`), and install it the way your client loads skills.

## Step 5: read more

The documentation index is `https://docs-preview.plungeai.com/llms.txt`. Append `.md` to any page URL on docs-preview.plungeai.com, or send `Accept: text/markdown`, to read the page as markdown.

## Rules

- Discovery first: search for an agent, tool or workflow before you call one, and take ids only from live results, never from memory.
- When a tool answers "AWAITING USER APPROVAL", relay the block to the user and call `plungeai_continue` only after the user answers. A trust-fence "NEEDS APPROVAL" can be approved only in Ocean Studio.
- On any error, report the `x-request-id` of the failing response to the user.
- Never print, log or commit the key.