# Coconut MCP: agent setup and first calls

Use this guide to connect an agent to Coconut and check its authorized scope.

- MCP endpoint: https://coconutapp.xyz/api/mcp
- Host setup: https://coconutapp.xyz/docs/agent-setup
- Tool reference: https://coconutapp.xyz/docs/mcp-tools/overview
- Grants and receipts: https://coconutapp.xyz/docs/mcp-tools/governance

## Release profile

The default release profile contains 47 business tools and two helpers.
MCP uses the existing Coconut operations and ontology.
This guide describes the release profile. It does not prove deployment or Production acceptance.
Discovery from the connected server determines which tools are available to this credential.
A narrow grant can expose fewer than 49 tools.
Do not enable the wider catalog to bypass a missing tool or capability.

## Maris and MCP coverage

Maris has 44 selectable tools. This MCP profile exposes 41 matching Maris names, six additional workflow tools, and two helpers.
Matching names do not prove identical schemas or complete workflow qualification.

| Domain | Selectable Maris tools | Matching MCP names |
| --- | ---: | ---: |
| Workspace navigation | 3 | 3 |
| Brand management | 3 | 2 |
| Channels | 1 | 1 |
| Sources, subscriptions, ingestion, and analysis | 12 | 12 |
| Vault | 6 | 6 |
| Assets, branches, and history | 10 | 10 |
| Publication and readiness | 8 | 6 |
| Web search | 1 | 1 |
| Total | 44 | 41 |

The absent Maris names are `brand_switch`, `asset_publication_command_create`, and `publication_command_retry`.
MCP credentials bind one Brand. Use another explicit consent grant for another Brand.
Use the documented single-branch `publication_propose` workflow for publish-now or scheduling.
The canonical batch-create wrapper and manual publication retry are unavailable.
The six additional workflow tools are `publication_readiness`, `publication_propose`, `publication_status`, `media_upload_begin`, `media_upload_complete`, and `media_status`.
Do not interpret the broader internal catalog as callable tools.

## Connect

Use native HTTP MCP with OAuth when the installed host supports it.
A native connection needs no Coconut checkout, local server, or npm package.
Check the installed host version and command help before configuration.
Preserve existing MCP server entries.
Use one authentication method per server entry.

### Codex

Add this entry to the active Codex `config.toml`:

```toml
[mcp_servers.coconut]
url = "https://coconutapp.xyz/api/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 300
```

Start OAuth login:

```bash
codex mcp login coconut --oauth-client-registration dcr --scopes mcp_access
```

Check the connection:

```bash
codex mcp list
```

Command help and a registered server do not prove a successful tool call.
Host tool permissions and Coconut capabilities both apply.

### Other hosts

Use the version-specific configurations in the website setup guide:

- Claude Code: https://coconutapp.xyz/docs/agent-setup#claude-code
- OpenCode: https://coconutapp.xyz/docs/agent-setup#opencode
- Hermes: https://coconutapp.xyz/docs/agent-setup#hermes
- Modern OpenClaw: https://coconutapp.xyz/docs/agent-setup#openclaw
- Codex on a VPS: https://coconutapp.xyz/docs/agent-setup#vps

For non-interactive Claude Code, wait for MCP startup before the first model request.
Current Claude Code supports `MCP_CONNECTION_NONBLOCKING=0` for this check.
Check that Coconut is connected and its tools reach the model. A pending connection can leave that request without tools.
Reference: https://code.claude.com/docs/en/mcp#exempt-a-server-from-deferral

These configurations do not prove native acceptance for every host or tool.
The older Coconut OpenClaw plugin uses a separate interface.
Do not infer the default profile from that plugin's tool list.

## Authorize the connection

1. Start the host's native OAuth login.
2. Open the authorization page from the terminal link.
3. Sign in to Coconut.
4. Check the Workspace and Brand.
5. Select only the operations that the requested workflow requires.
6. Check the expiry, client name, and callback destination.
7. Complete consent.

Use the admitted development endpoint for development consent.
Do not send development credentials to Production.
New capabilities require fresh consent.
Refresh cannot expand the grant or extend its absolute expiry.
Disconnect the grant in Coconut to revoke server access.
Removing local credentials does not replace server revocation.

For an unsupported host or unattended workflow, create a scoped MCP key in Settings → API Keys.
Include `workspace_discover` for the connection check.
Supply `COCONUT_API_KEY` through a secret manager or protected host environment.
Use an environment reference in host configuration.
Keep credentials out of chat, arguments, committed files, and logs.
Never copy a token from another host's credential store.
Enter an OAuth callback only through the host's approved callback flow or a hidden terminal prompt.
Do not send callback URLs through chat or terminal-send.
The Coconut login helper hides URL parameters in the visible link label.
It shows only the last four characters of a client reference.
It rejects credential parameters before it displays a link.
Enter a callback only while the hidden prompt is active.
Do not enter a callback after the login flow stops.

When the browser runs on another machine, `localhost` refers to the browser's machine.
Check the app origin and callback listener from that browser before login.
For a development app, forward the same laptop and server port as the configured app origin.
The callback listener can require a separate forward.
Keep the configured OAuth issuer unchanged.
Use the host's documented forwarding method or the approved hidden callback prompt.

## First calls

1. Discover the tools and their complete input schemas.
2. Call `workspace_get` with `{}`.
3. Check the returned Workspace, Brand, capabilities, and expiry.
4. Report the authorized scope before making changes.
5. Read an authorized target with `workspace_find`, `workspace_read`, or `workspace_query` when available.
6. Use `channel_list` before a workflow that needs a connected channel.
7. Use current identifiers and versions from those reads.

Do not invent tool names, target IDs, versions, actor IDs, or scope overrides.
Host tools can include a namespace around the server tool name.
Follow the discovered schema for invocation and idempotency fields.
Make changes only for the requested workflow.
Use `operation_receipts` to inspect evidence for an invocation.

## Check unattended access

The first read proves that connection only.
Repeat the read after the access token expires.
Start a new process with the same profile.
Check the Workspace, Brand, credential, grant version, and capabilities.
Let the native client refresh its tokens.
Never copy or edit tokens for a lifecycle test.

Use separate consent and token storage for each agent installation.
Workers that share token storage must coordinate refresh across processes.
Record the client version, server release, UTC time, failing step, safe error code, and request ID.
Keep prompts, tool payloads, callback URLs, headers, and credentials out of diagnostics.
Recheck this lifecycle after OAuth, grant, SDK, installer, storage, or host-configuration changes.
Keep absent native-client evidence explicit.

## Verified client boundaries

On October 20, 2026, Codex 0.162.1, the installed Hermes runtime, Claude Code 2.1.292,
OpenCode 1.18.35, and OpenClaw 2026.10.5 each passed the six added invalid-input explanation and recovery checks.
The scoped OpenCode test grant exposed eight tool names. The other test profiles exposed 49.
Hermes, OpenCode, Claude Code, and OpenClaw also read ready Media, publication readiness, and a cancelled publication.
On Production 2.9.686, OpenCode, Claude Code, and OpenClaw each submitted a separate future test publication that reached scheduled.
All three test publications then reached cancelled. No public publish-now test ran.
Codex also verified rescheduling, cancellation, and automatic Calendar updates.
The CLI checks used deterministic tool selection without model provider requests.
These results prove the named operations and client parsing.
Every positive tool workflow, native host upload completion, other model choices, and the original remote Hermes VPS remain separate verification boundaries.

## Error explanations and safe recovery

A failed request returns a safe code, an explanation, and a recovery instruction.
Tool failures also return `recovery.action` and `recovery.retryDisposition`.
For `MCP_ACCEPT_INVALID`, set `Accept: application/json, text/event-stream` in the HTTP client.
For `MCP_PROTOCOL_VERSION_UNSUPPORTED`, use the protocol version returned by `initialize` in `MCP-Protocol-Version`.
Initialize a new connection if the client has no negotiated protocol version.
Use the request ID and invocation ID when the response supplies them.
For `INPUT_INVALID`, read `invalidFields` and the discovered input schema.
Correct the fields before another request.
Do not repeat the same invalid input.
A connection failure does not establish that an operation failed before its effect.
For an uncertain mutation outcome, inspect `operation_receipts` and current state before another mutation.
Stop automatic retries after a scope, consent, or credential rejection.
Ask an authorized Workspace member to check the selected scope when required.
Never change target identifiers to bypass access controls.
A recovery instruction does not expand the current grant or the user's requested workflow.

## Workflow limits and recovery

- Use `creator_subscribe` to create a subscription.
- Use `creator_subscription_update` to change or cancel it.
- Subscription creation does not prove ingestion.
- Use `content_ingest` to request creator content.
- Use `content_analyze` only for content delivered to the authorized Brand.
- Analysis, ingestion, and web search can consume credits or provider usage.
- Use `asset_create_structured` for Asset creation.
- Read branches before `asset_branch_operation_apply`.
- Inspect publication readiness before supported repairs or scheduling.
- Import reuse scheduling requires its exact approved 100-item manifest.
- `import_reuse_schedule` is not a general single-post publish command.
- Use `publication_readiness` to read the exact binding for one Asset branch.
- Use `publication_propose` to publish that branch or schedule it at an absolute timestamp.
- Use `publication_status` to read the durable publication state.
- Existing grants do not gain publication permissions automatically. Authorize a new grant with `publication_propose` and `publication_status` when required.
- Interactive approval and `publication_resume` are unsupported. An authority denial must stop the request.
- Media upload uses `media_upload_begin`, `media_upload_complete`, and `media_status`. Transfer local file bytes through the protected helper.
- The private upload helper requires separately enabled tools and its own authorization.
- The helper has no public npm installation.

### Publish or schedule one Asset branch

1. Create the Asset with `asset_create_structured`.
2. Create or select its channel branch with `asset_branch_create` or `asset_branch_list`.
3. Call `publication_readiness` with the Asset, branch, channel, selected post kind, timezone, and warning acknowledgements.
4. Set `scheduledAt` to `null` for immediate publication. Set it to an absolute timestamp with an offset for scheduling.
5. Copy `branchRevisionId`, `contentDigest`, `mediaDigest`, and `socialAccountId` from the returned `binding` into `publication_propose`.
6. Preserve the inspected intent fields. Supply a stable `idempotencyKey` for this publication request.
7. Use bounded `publication_status` reads with the returned `publicationId`. For scheduling, confirm `scheduled`. Check the requested time in the Calendar. For publish-now, confirm terminal publication.

A stable foreground Calendar checks for external agent changes every 30 seconds. A Calendar with transitional work checks every 2 seconds. Background polling is disabled. Do not repeat a mutation because the Calendar has not updated yet.

This workflow admits one branch per request. It does not accept a channel batch or a local wall-clock time.
The grant must include `publication_readiness`, `publication_propose`, and `publication_status`.
The readiness grant exposes both readiness tools.
An existing grant without publishing permission must remain read-only until an authorized member explicitly grants publishing permission.
Do not invent digest values or submit an approval identifier.
For a changed binding, inspect readiness again before a new request.
For an unknown outcome, read status and receipts before any retry. Preserve the original idempotency key and input.

An accepted or queued operation does not prove completed ingestion, analysis, or provider publication.
After a timeout or an unknown result, inspect receipts and current state before retrying.
Do not create a new operation to bypass an uncertain outcome.
For a stale target, read the current target before another request.
For `EXTERNAL_LIMIT_EXCEEDED`, wait until the next UTC hour before starting a new operation.
Governed operations allow 100 reservations per credential and client per UTC hour.
Agents for the same actor and Workspace share a 200-reservation hourly limit.
The Workspace also shares a 1,000-reservation hourly limit.
Completed idempotent replays do not reserve another operation.
Creating another agent connection does not reset the shared limits.
For `EXTERNAL_CAPABILITY_DENIED`, obtain fresh consent or a replacement key with the required capabilities.
For `MCP_KEY_REPLACEMENT_REQUIRED`, replace the legacy key.
For expiry, revocation, or refresh rejection, stop the workflow and obtain fresh consent.
Host permission cannot expand a Coconut grant.

## Helpers

| Tool | Purpose |
| --- | --- |
| `workspace_get` | Read the credential's Workspace, Brand, capabilities, expiry, and channel context. Start with `{}`. |
| `operation_receipts` | Read governed evidence for an invocation in the authorized Brand. |

## Business tools

### Brand (2)

| Tool | Purpose |
| --- | --- |
| `brand_create` | Create a Brand in the authorized Workspace. |
| `brand_update` | Update Brand identity and Brain settings with version checks. |

### Workspace and channels (4)

| Tool | Purpose |
| --- | --- |
| `workspace_find` | Find authorized objects through the shared ontology. |
| `workspace_read` | Read an authorized object and its current state. |
| `workspace_query` | Query authorized objects through the shared ontology. |
| `channel_list` | Read connected channels and their current state. |

### Sources and analysis (5)

| Tool | Purpose |
| --- | --- |
| `creator_subscribe` | Subscribe the Brand to a creator. |
| `creator_subscription_update` | Update or cancel a creator subscription. |
| `creator_analyze` | Analyze a creator within the authorized scope. |
| `content_analyze` | Analyze content delivered to the Brand. |
| `content_ingest` | Request content ingestion for a creator. |

### Sources organization (7)

| Tool | Purpose |
| --- | --- |
| `sources_collection_create` | Create a Sources collection. |
| `sources_collection_update` | Update a Sources collection. |
| `sources_tag_create` | Create a Sources tag. |
| `sources_tag_update` | Update a Sources tag. |
| `sources_membership_update` | Update Sources collection or tag membership. |
| `sources_reference_update` | Update a Sources reference. |
| `sources_stash_update` | Update the Sources stash state. |

### Vault (6)

| Tool | Purpose |
| --- | --- |
| `vault_collection_create` | Create a Vault collection. |
| `vault_collection_update` | Update a Vault collection. |
| `vault_tag_create` | Create a Vault tag. |
| `vault_tag_update` | Update a Vault tag. |
| `vault_membership_update` | Update Vault collection or tag membership. |
| `vault_notes_update` | Update Vault notes. |

### Media upload (3)

| Tool | Purpose |
| --- | --- |
| `media_upload_begin` | Admit one file by byte count, MIME type, and checksum. |
| `media_upload_complete` | Commit acknowledged parts and request verification. |
| `media_status` | Confirm verified Media readiness before Asset reuse. |

### Assets and history (10)

| Tool | Purpose |
| --- | --- |
| `asset_create_structured` | Create an Asset from structured input. |
| `asset_operation_apply` | Apply an operation to an Asset. |
| `asset_branch_list` | Read the branches of an Asset. |
| `asset_branch_create` | Create an Asset branch. |
| `asset_branch_operation_apply` | Apply an operation to an Asset branch. |
| `asset_branch_diff` | Compare Asset branch state. |
| `asset_journal_read` | Read Asset history. |
| `asset_journal_undo` | Undo an eligible Asset history entry. |
| `asset_journal_redo` | Redo an eligible Asset history entry. |
| `asset_journal_restore` | Restore an eligible Asset history revision. |

### Publication and import reuse (9)

| Tool | Purpose |
| --- | --- |
| `asset_publication_readiness_inspect` | Inspect publication requirements and blockers. |
| `publication_readiness` | Read readiness and the exact binding for a publication request. |
| `publication_propose` | Publish or schedule one Asset branch under the explicit grant. |
| `publication_status` | Read the durable state of a publication. |
| `asset_publication_readiness_repair` | Apply a supported publication readiness repair. |
| `import_reuse_prepare` | Prepare imported content for reuse. |
| `import_reuse_schedule` | Admit an approved import reuse manifest for scheduling. |
| `asset_publication_cancel` | Cancel an eligible publication. |
| `asset_publication_reschedule` | Reschedule an eligible publication. |

### Web search (1)

| Tool | Purpose |
| --- | --- |
| `web_search` | Search the web through the configured provider. |