Agent setup

Connect Hermes

One config entry, then browser consent from your Hermes host.

Copy these instructions into Hermes, or follow the steps below.

Before configuration

Check the installed Hermes version and command help. Preserve existing server entries. Inspect the current Coconut entry before adding or replacing it. Stop if the installed host lacks native HTTP MCP OAuth support.

Configure the connection

Merge configuration examples into the existing file. Do not replace the complete file. Do not add an Authorization header for native OAuth. Coconut uses the mcp_access scope, PKCE S256, and dynamic client registration.

~/.hermes/config.yaml
mcp_servers:
  coconut:
    url: https://coconutapp.xyz/api/mcp
    timeout: 300
    auth: oauth
    oauth:
      scope: mcp_access
      cimd: false

Run hermes mcp login coconut in a fresh terminal on the machine that runs Hermes. Complete browser consent. Use /reload-mcp in the agent session after login.

Let the human sign in and choose the workspace, brand, and access level. Never request credentials in chat. Never approve consent for the human. Keep tokens and callback URLs out of prompts, command arguments, and logs.

For a remote host, confirm that the browser can reach its callback listener. Use the host's documented secure forwarding method. If that path is unavailable, stop and report the missing requirement. Do not submit a callback code through a command argument. Coconut does not provide device authorization.

For a local development server on another machine, check the configured app origin in the actual consent browser. Forward the same laptop and server port. Check the sign-in redirect and consent page before starting login. Server health alone does not prove browser access. The OAuth callback listener can require a separate forward.

Check the tools

Ask Hermes to discover Coconut tools and call workspace_get with {}. A saved configuration alone does not prove agent access.

Check the returned Workspace, Brand, capabilities, and expiry. Report the discovered tool names. The default profile contains 47 business tools plus two connection and evidence helpers. Discovery can return a smaller grant. Do not enable feature flags or widen access to obtain missing tools.

Report any failure with the failing step and safe error code. Do not claim a working connection from registration or a tool count. Wait for the user's requested workflow before changing Coconut data. After an unknown mutation result, read current state and operation_receipts before retrying.

A rejected request includes a safe code, an explanation, and a recovery instruction. For INPUT_INVALID, read invalidFields and the discovered input schema. Correct the fields before another request. Do not repeat the same invalid input. Stop automatic retries after scope or credential rejection. A recovery instruction does not expand the grant or authorize another mutation.

For EXTERNAL_LIMIT_EXCEEDED, read limit.bucketKind, limit.used, limit.limit and limit.resetAt. Wait retryAfterSeconds, then send the same request with the same idempotency key. Only writes count: reads never use this budget. Each credential and client may make 250 writes per UTC hour. Agents for the same actor and Workspace share 500 writes per UTC hour. The Workspace shares 1,000 writes per UTC hour. Completed idempotent replays do not count again. Another connection does not reset shared limits.

Check unattended access

A first successful read proves that connection only. Before unattended use, repeat the read after the access token expires. Start a new process with the same profile. Check the Workspace, Brand, credential, capabilities, and a second read. Let the client refresh its own tokens. Never copy or edit tokens to run this check.

Use a separate grant and separate token storage for each agent installation. Two agents can select the same Workspace and Brand. Workers with shared token storage must coordinate refresh across processes. Copying one token file to another host can cause refresh replay and revoke that grant.

Record the client version, SDK version when available, server release, UTC time, failing step, safe OAuth error, and request ID. Keep authorization URLs, callback URLs, headers, tokens, and token hashes out of the report. A refresh rejection occurs before a tool call and needs separate evidence.

Recheck this lifecycle after an OAuth, grant, SDK, installer, token-storage, or host-configuration change. Documentation describes the connection method. It does not establish native acceptance for an untested client version.

A Hermes 0.21.0 installation with MCP SDK 2.0.0 can omit resource from a refresh request after restart. Its first login can succeed. Use the pinned repair guide at https://coconutapp.xyz/agent-repairs/hermes-oauth.md for the complete patch, checksums, installation, and restart checks. The guide does not establish repair of your installation. The pinned repair also handles a resource HTTP 401 when the client still considers its access token valid. That condition requires one coordinated refresh before browser authorization. An invalid_target refresh needs client resource handling diagnosis. Do not disable server audience validation.

Detailed reference

Codex

Next