MCP Governance and Usage

Credentials and scope

Each OAuth grant or MCP key belongs to one human requester, workspace, brand, and API client. The grant permits selected capabilities and has an expiry. Coconut stores hashes of API keys and OAuth tokens. The human requester and API client remain distinct in governed evidence.

Use HTTPS for hosted connections. Keep credentials in a protected host store or helper profile. Keep credentials out of plugin packages, URLs, command arguments, prompts, and committed configuration. The private helper rejects redirects and unapproved endpoint origins. Each native host has its own transport behavior.

The grant authorizes selected operations

Select operations during OAuth consent or MCP key creation. The grant authorizes those operations without further Coconut approval. Include publication only when you intend the agent to publish or schedule posts. Your current brand authority, usage limits, and target validation still apply.

Harness Always allow, Ask, and Never settings control Maris. They do not control external credential grants. Your agent can still require its own permission before it sends a tool call. Host permission cannot expand the grant scope or your current brand authority.

For EXTERNAL_CAPABILITY_DENIED, obtain fresh OAuth consent or a replacement key with the required operations. For MCP_KEY_REPLACEMENT_REQUIRED, replace the legacy key with a new MCP key. Coconut does not upgrade existing keys to unattended execution. For TARGET_STALE, inspect the target and submit current identifiers and versions.

New OAuth capabilities require fresh consent. Refresh cannot expand the grant or extend its absolute expiry.

Disconnect an OAuth grant on the OAuth connections page. Then verify MCP and refresh rejection.

Revoke and replace a key

1. Open Settings → API Keys.
2. Revoke the key.
3. Verify that a new workspace request with that key fails.
4. Create a replacement with the required capabilities and expiry.
5. Replace the protected credential and restart the agent.

Revocation prevents new admission and invalidates the credential grant. It cannot undo a provider effect that already occurred. Use publication status and canonical cancellation for an existing publication.

Receipts and usage tracking

Admitted operations retain invocation, decision, and receipt references. Mutations also retain domain effect evidence. Use operation_receipts to inspect evidence within your brand.

Coconut records per-credential tool usage with the method mcp.tool:TOOL_NAME, result, duration, and error code. The server emits mcp.operation.completed to configured PostHog analytics and starts an OpenTelemetry span. An explicit field allowlist excludes payloads, captions, file bytes, and credential values.

Analytics delivery is best effort. Missing configuration disables PostHog delivery. Governed receipts provide operation evidence. An accepted analytics event does not prove terminal provider success.

The event distinguishes tools, accounts, and API clients. It does not reliably identify which agent application made the call. A client label must not be treated as an authenticated identity.