Agent Setup

Use HTTP MCP to connect an agent to Coconut. No local Coconut checkout or npm package is required for a native connection.

The default release profile contains 47 business tools and two helpers. Discovery returns only the tools that your deployment and credential permit.

Give your agent the Markdown setup guide or copy this instruction:

Read https://coconutapp.xyz/agent-setup.md. Configure Coconut MCP for my installed host. Use native OAuth when supported. Discover tools. Call workspace_get with {}. Report the Workspace, Brand, available tools, and expiry. Wait for my requested workflow before making changes.

Authorize one client

Use an OAuth-enabled deployment at https://coconutapp.xyz/api/mcp. Configure the URL without a bearer header. Start the host's native OAuth login. Sign in to Coconut in the browser. Choose Read and write when the workflow needs changes. Choose Read only to view information without making changes. Open Customize access for individual operations. Confirm the workspace and brand. Coconut selects them automatically when only one accessible choice exists. Review the expiry, client name, and callback destination before consent.

Consent authorizes selected operations without further Coconut approval. Host tool permissions still apply. Current member authority, revocation, expiry, quotas, and target checks still apply. New capabilities require fresh consent. Refresh cannot expand the grant or extend its absolute expiry. Development consent must use its development deployment.

These examples describe native host configuration. Verify your installed version before use. Installation and command help do not prove a successful Coconut connection.

Verified client access

Historical Production verification on October 8, 2026 used Coconut 2.9.651. These results do not prove Production acceptance of the current profile. Each client requires its own consent and host tool permissions. A verified operation does not prove every operation in that client.

• Codex 0.161.0: native OAuth login, workspace discovery, Asset creation, operation receipts, and natural token refresh.
• OpenCode 1.18.35: native OAuth login and an agent workspace read with workspace_discover. Write tools remained unverified in that historical run.
• Private media helper: separate OAuth consent, real video upload, ready Media, and Asset creation from that Media.
• October 8 historical boundary: native Coconut OAuth acceptance for Claude Code, Hermes, and modern OpenClaw was unverified. The October 20 checks below update these client boundaries.

Publication and scheduling require separate provider acceptance. The verified X journeys used a scoped API key and the MCP SDK. Remote callback intake remains a separate verification boundary.

On October 20, Codex 0.162.1, the installed Hermes runtime, Claude Code 2.1.292, OpenCode 1.18.35, and OpenClaw 2026.10.5 each passed invalid-input explanation and recovery checks for the six added Media and publication tools. The scoped OpenCode test grant exposed eight tool names. The other test profiles exposed 49. Discovery follows each grant's capabilities.

Hermes, OpenCode, Claude Code, and OpenClaw 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. Other model choices, every positive tool workflow, native host upload completion, and the original remote Hermes VPS remain separate verification boundaries.

A stable foreground Calendar checks for external agent changes every 30 seconds. Transitional work retains a 2-second check. Background polling is disabled. Read publication status before any mutation retry.

Codex

Add this entry to config.toml. Preserve existing server entries.

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

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

Check supported flags with codex mcp login --help. Use codex mcp list to inspect the connection.

Codex applies its own tool approval settings. Approve only the tools that your workflow requires:

[mcp_servers.coconut.tools.asset_create_structured]
approval_mode = "approve"

The private plugin uses plugins."coconut-agent-access@coconut-private".mcp_servers.coconut.tools.<tool>. Use either the plugin or direct configuration for one connection. Host permission does not grant Coconut capabilities.

Codex MCP reference

Claude Code

Add this entry to your project .mcp.json. Preserve existing server entries.

{
  "mcpServers": {
    "coconut": { "type": "http", "url": "https://coconutapp.xyz/api/mcp" }
  }
}

Start Claude Code. Review the project server permission. Use /mcp to authenticate Coconut.

This example does not configure Claude Desktop or claude.ai. Verify native access with your installed Claude Code version.

Claude Code MCP reference

OpenCode

Add this entry to opencode.json. Preserve existing server entries.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coconut": { "type": "remote", "url": "https://coconutapp.xyz/api/mcp", "oauth": { "scope": "mcp_access" } }
  }
}

opencode mcp auth coconut

Installed OpenCode 1.18.35 exposes this command. Use opencode mcp list for connection status. OpenCode tool permissions and Coconut capabilities both apply. VPS callback intake remains unverified. Do not paste a callback into a command argument.

OpenCode MCP reference

Hermes

Use a Hermes version with native OAuth and DCR support. Add this entry to config.yaml:

mcp_servers:
  coconut:
    url: https://coconutapp.xyz/api/mcp
    auth: oauth
    oauth:
      cimd: false

Connect in Hermes to start browser consent. Verify the installed version and native Coconut access.

The older Hermes API-key proof does not prove OAuth support. Coconut does not offer device authorization.

Hermes MCP reference

Modern OpenClaw

Use a version with native outbound MCP OAuth. Check openclaw mcp --help before configuration.

openclaw mcp set coconut '{"url":"https://coconutapp.xyz/api/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"mcp_access"}}'
openclaw mcp login coconut

Verify that your agent runtime consumes the saved MCP entry. Native registry configuration does not prove runtime access. The former Coconut OpenClaw plugin has a separate API-key contract.

OpenClaw native MCP OAuth reference

Codex on a VPS

From an approved Coconut checkout, use the hidden callback wrapper in a visible terminal. Check the worktree, execution host, hostname, and script path first. Use an isolated client profile for initial acceptance.

python3 scripts/mcp-oauth-login.py --client codex --registration dcr

Open the printed authorization URL in your browser. Complete consent. Enter the complete callback URL at the hidden terminal prompt. The wrapper forwards it unchanged to Codex. Never send the callback through chat, terminal-send, arguments, or a file. OpenCode VPS callback support requires a separate proof.

Private media helper availability

The default profile includes governed media upload admission, completion, and status. Use the protected helper below to transfer local file bytes. Check discovery before upload. Do not enable the wider catalog to bypass a missing tool.

The private media helper requires its own consent and protected OAuth profile. It never copies native host tokens. The package is private and has no public npm installation.

python3 scripts/mcp-oauth-login.py --client helper -- \
  --workspace-id "$COCONUT_EXPECTED_WORKSPACE" \
  --brand-id "$COCONUT_EXPECTED_BRAND" \
  --capabilities "$COCONUT_EXPECTED_CAPABILITIES"
node packages/coconut-agent-access/src/cli.mjs upload \
  --file "$APPROVED_MEDIA_FILE" --mime-type video/mp4 --media-kind video

One helper grant covers upload begin, byte transfer, acknowledgment, and completion. OAuth uploads cannot reuse another client's session. Check scan and ready state before using the returned Media ID in an Asset.

Video metadata for YouTube

Measure duration and dimensions from the file before upload. Supply all three measured values. Coconut stores these values as declared metadata. Byte verification, checksum and malware scan remain required.

node packages/coconut-agent-access/src/cli.mjs upload \
  --file "$APPROVED_MEDIA_FILE" --mime-type video/mp4 --media-kind video \
  --video-duration-ms "$VIDEO_DURATION_MS" \
  --video-width "$VIDEO_WIDTH" --video-height "$VIDEO_HEIGHT"

Duration uses integer milliseconds. Width and height use integer pixels. Missing metadata blocks YouTube publication. Use a fresh upload to add metadata.

API-key fallback

For an unsupported host or an unattended workflow, create a brand-bound MCP key in Settings → API Keys. Select a brand, an access preset, and expiry. Read and write permits reads and the available changes. Read only excludes operations that make changes. Open Customize access to select individual operations. Supply COCONUT_API_KEY through a secret manager or hidden terminal intake. Keep the value out of chat, arguments, committed files, and logs.

• Codex: add bearer_token_env_var = "COCONUT_API_KEY" to the server entry.
• Claude Code: add "headers": { "Authorization": "Bearer ${COCONUT_API_KEY}" } to the server entry.
• OpenCode: set oauth: false and use "headers": { "Authorization": "Bearer {env:COCONUT_API_KEY}" }.
• Hermes: replace OAuth settings with headers: { Authorization: "Bearer ${COCONUT_API_KEY}" }.
• Private helper: use --auth api-key --key-file "$COCONUT_KEY_FILE".

The older Coconut OpenClaw plugin uses a separate API-key interface. It does not provide the current profile. Prefer native HTTP MCP. For an explicitly required legacy deployment, use an approved version 0.3.0 checkout:

cd packages/openclaw-plugin
bun install
bun run build
cd ../..
openclaw plugins install -l ./packages/openclaw-plugin

Supply COCONUT_API_KEY through the protected gateway environment. Enable the plugin and permit only required coconut_* tools.

Use one authentication method per server entry. A development key must use its development deployment.

Verify access and disconnect

1. Discover tools in the native agent.
2. Call workspace_get with {}.
3. Check workspace, brand, capabilities, and expiry.
4. Read an authorized target with a discovered Workspace tool.
5. Verify a requested operation and token refresh before automation.
6. Read operation_receipts and current state after a change.

Disconnect the grant on Coconut's OAuth connections page to revoke server access. Removing local credentials does not replace server revocation. After expiry, revocation, or refresh rejection, stop the workflow and obtain fresh consent.

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 host permission denial, review the host permission.

Use current identifiers and versions. Follow the discovered schema for invocation and idempotency fields. After a timeout or an unknown result, inspect receipts and current state before retrying. An accepted operation does not prove completed ingestion, analysis, or provider publication.

Read the current tools and governance contract.