# Connect Claude Code or Codex (MCP)

Volae is a remote MCP server. Your agent signs in with your Volae account (OAuth); there is no key to copy. Where OAuth doesn't fit (CI, a script, a machine with no browser), connect with an [access token](#connect-with-an-access-token).

| | |
|---|---|
| Server URL | `https://api.volae.net/mcp` |
| Compact server | `https://api.volae.net/mcp/compact` (three tools instead of the full list; see below) |
| Auth | OAuth 2.1 with dynamic client registration, or an access token |

## Claude Code

```bash
claude mcp add --transport http volae https://api.volae.net/mcp
```

Then run `/mcp` in Claude Code and choose **volae** to sign in.

## Codex

```bash
codex mcp add volae --url https://api.volae.net/mcp
codex mcp login volae
```

## Connect with an access token

Create a token in **Settings → Access tokens** and send it as a bearer token. The token's permission applies; see [below](#what-a-connected-agent-can-do).

```bash
claude mcp add --transport http volae https://api.volae.net/mcp/compact --header "Authorization: Bearer vol_…"
```

Or in `.mcp.json`, reading the token from the environment so it stays out of your repository:

```json
{
  "mcpServers": {
    "volae": {
      "type": "http",
      "url": "https://api.volae.net/mcp/compact",
      "headers": { "Authorization": "Bearer ${VOLAE_TOKEN}" }
    }
  }
}
```

Calling it without an MCP client: send `Accept: application/json, text/event-stream` on every request, and read the JSON from the `data:` line of the response, which comes back as server-sent events.

```bash
curl -s https://api.volae.net/mcp/compact \
  -H "Authorization: Bearer vol_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_tools", "arguments": { "query": "search people" } } }'
```

```
event: message
data: {"result":{"content":[{"type":"text","text":"{\"actions\":[…]}"}]},"jsonrpc":"2.0","id":1}
```

## What a connected agent can do

There are three permissions: **Read** (`read`), **Read & write** (`write`) and **Approve & send** (`act`). A newly connected agent gets Read & write: it can read everything in your workspace and create drafts, proposals and internal records. It can't approve proposals or send anything to anyone. You can turn on Approve & send for a specific agent only in the Volae web app (**Settings → Claude Code & Codex**), and you get a security email when that happens. Destructive actions (deleting things) always need confirmation in the web app.

Disconnecting an agent in Settings stops it immediately: its next call returns 401.

## Full vs compact

The full server lists every action as its own tool: about 460 tools and about 1540 KB of descriptions and schemas in every `tools/list`. Most clients should use the compact server, which has three tools and looks the rest up when needed:

| Tool | Arguments | What it does |
|---|---|---|
| `search_tools` | `query` (keywords; empty lists every action by name), `limit` (1–30, default 8) | Finds actions, with each one's description, input schema and which tool to call it with |
| `call_read` | `name`, `arguments` | Runs a read action |
| `call_write` | `name`, `arguments` | Runs an action that changes data |

```json
{ "name": "search_tools", "arguments": { "query": "search people", "limit": 3 } }
{ "name": "call_read", "arguments": { "name": "search_people", "arguments": { "query": "ana", "limit": 5 } } }
{ "name": "call_write", "arguments": { "name": "remember", "arguments": { "scope": "product", "product": "notely", "content": "Refund window is 14 days", "source": "run" } } }
```

Tool arguments are checked against the action's input schema. A field the action doesn't have is refused with `invalid_input`, not ignored.

## Common sequences

| To do this | Call, in order |
|---|---|
| See what to do today | `get_standup`, then `get_proposal` for anything in "needs you", then `approve_proposal` or `reject_proposal` |
| Write to someone | `search_people`, `get_person_context`, then `draft_warm_email` (or `get_warm_email_context`, write it yourself, and save with `draft_warm_email` and `written`). A person approves it before it goes |
| Answer a conversation | `list_conversations`, `get_conversation`, then `draft_reply` (or `get_draft_context`, and `draft_reply` with `written`) |
| Look something up | `lookup_start`, answer `resolution` if it isn't `ready`, `lookup_run_blocks` with `estimateOnly` to see the price, `lookup_run_blocks`, then `get_lookup` until no block is `running` |
| Track AI answers | `suggest_geo_prompts`, `save_geo_prompt` for the ones you want, `run_geo` with `estimateOnly`, `run_geo`, then `get_geo_overview` when `list_geo_runs` says it's done |
| Remember something | `get_context_pack` to see what's known, `remember`, then `list_memories` to read it back (see [Memory](memory.md)) |
| See what changed and take it back | `list_changes`, then `undo_change` or `redo_change` |
| Take a draft through to approval | `propose_publish`, `get_proposal` until its checks finish, `submit_proposal` after fixing what failed. A person approves publishing in the web app |
| Work on a goal | `list_goals`, `get_goal` for its stages, `create_work`, then `get_stage_check` for the verdict |
| Check where a profile line came from | `get_profile_blocks`, `get_block_source`, then `get_source_event` for the raw record |
| Handle what the coworker noticed | `list_findings`, then `update_finding` or `propose_world_fix` |
| Read the history in git | `export_changes_git`, following `nextCursor` (see [Commits, proposals, goals and works](workbench.md)) |

## Memory

Read before you act and write down what you learn: `get_context_pack` for what to know about a person, company, product, theme or goal (including the user's standing instructions), `recall` to search, `remember` to write. See [Memory](memory.md).

## Writing with your own model

Each writing action has a context action that returns the rules and material, calls no model and uses no credits. Your agent writes with its own model and saves the result as a proposal. See [Write with your own Claude Code or Codex](own-agent.md).
