​
MCP troubleshooting

Most Ocoya MCP issues come from client configuration, incomplete OAuth approval, missing brand access, or passing IDs from the wrong brand.

​
Quick checks

SymptomWhat to check
Client does not list Ocoya toolsConfirm the MCP URL is https://mcp.ocoya.com, restart the client, and make sure the client supports remote HTTP MCP servers.
OAuth opens but access is deniedSign in to the correct Ocoya account and approve at least one brand.
401 responseThe client has not completed OAuth, the access token expired, or the client is sending an API key instead of using OAuth.
Brand not foundThe brand was not selected during approval, or the client is using a brand ID from another Ocoya account.
Social profile rejectedCall ocoya_list_social_profiles for the same brandId and use one of the returned IDs.
Invalid scheduleUse an ISO datetime such as 2026-07-01T09:00:00Z.
Workflow cannot be enabledResolve workflow validation errors in Ocoya before toggling or running it.

​
OAuth and authorization

Ocoya MCP does not accept Ocoya API keys. MCP clients should use OAuth and send a bearer token issued by Ocoya after the user approves access.

For diagnostics, an unauthenticated request should return 401 with a WWW-Authenticate header that points to Ocoya OAuth metadata:

curl -i https://mcp.ocoya.com \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

If a client keeps failing OAuth, remove the Ocoya MCP connection from that client, add it again, and complete the approval flow from a browser where you can sign in to Ocoya.

​
Brand access

Brand-scoped tools require a brandId returned by ocoya_list_brands. If a brand is missing:

  1. Reconnect Ocoya MCP.
  2. Select the missing brand during the OAuth approval flow.
  3. Ask the client to call ocoya_list_brands again.

Do not reuse brand IDs from another account, environment, or OAuth grant.

​
Posting and scheduling

Before creating or scheduling posts, ask the client to resolve fresh IDs:

List my Ocoya brands and connected social profiles for the Acme brand.

Use the returned brandId and socialProfileIds in post tools. For scheduling, pass ISO datetimes:

2026-07-01T09:00:00Z

​
Client-specific notes

ClientCheck
Claude CodeQuote URLs if your shell treats special characters differently. Restart Claude Code after adding a new MCP server.
CodexRestart the app or open a new thread after editing ~/.codex/config.toml. Run codex mcp login ocoya when OAuth login is required.
VS CodeUse a recent VS Code version with MCP support and switch Copilot Chat to Agent mode.
Stdio-only clientsUse mcp-remote to bridge https://mcp.ocoya.com.

​
Safe recovery

If the connection looks stale or the wrong account is connected:

  1. Revoke or remove the Ocoya MCP connection in the client.
  2. Add the MCP server again.
  3. Complete OAuth with the intended Ocoya account.
  4. Select the brands the client should access.
  5. Verify with ocoya_list_brands before write actions.