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

Symptom	What to check
Client does not list Ocoya tools	Confirm 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 denied	Sign in to the correct Ocoya account and approve at least one brand.
`401` response	The client has not completed OAuth, the access token expired, or the client is sending an API key instead of using OAuth.
Brand not found	The brand was not selected during approval, or the client is using a brand ID from another Ocoya account.
Social profile rejected	Call `ocoya_list_social_profiles` for the same `brandId` and use one of the returned IDs.
Invalid schedule	Use an ISO datetime such as `2026-07-01T09:00:00Z`.
Workflow cannot be enabled	Resolve 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:

Reconnect Ocoya MCP.
Select the missing brand during the OAuth approval flow.
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

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

Safe recovery

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

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

Get Started

Tools

Troubleshooting

MCP troubleshooting

Quick checks

OAuth and authorization

Brand access

Posting and scheduling

Client-specific notes

Safe recovery

​MCP troubleshooting

​Quick checks

​OAuth and authorization

​Brand access

​Posting and scheduling

​Client-specific notes

​Safe recovery

MCP troubleshooting

Quick checks

OAuth and authorization

Brand access

Posting and scheduling

Client-specific notes

Safe recovery