Skip to main content

​
MCP troubleshooting

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

​
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 workspace.
401 responseThe client has not completed OAuth, the access token expired, or the client is sending an API key instead of using OAuth.
Workspace not foundThe workspace was not selected during approval, or the client is using a workspace ID from another Ocoya account.
Social profile rejectedCall ocoya_list_social_profiles for the same workspaceId 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.

​
Workspace access

Workspace-scoped tools require a workspaceId returned by ocoya_list_workspaces. If a workspace is missing:
  1. Reconnect Ocoya MCP.
  2. Select the missing workspace during the OAuth approval flow.
  3. Ask the client to call ocoya_list_workspaces again.
Do not reuse workspace 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 workspaces and connected social profiles for the Acme workspace.
Use the returned workspaceId 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 workspaces the client should access.
  5. Verify with ocoya_list_workspaces before write actions.