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

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

Workspace access

Workspace-scoped tools require a workspaceId returned by ocoya_list_workspaces. If a workspace is missing:

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

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 workspaces the client should access.
Verify with ocoya_list_workspaces before write actions.

Get Started

Tools

Troubleshooting

MCP troubleshooting

Quick checks

OAuth and authorization

Workspace access

Posting and scheduling

Client-specific notes

Safe recovery

​MCP troubleshooting

​Quick checks

​OAuth and authorization

​Workspace access

​Posting and scheduling

​Client-specific notes

​Safe recovery

MCP troubleshooting

Quick checks

OAuth and authorization

Workspace access

Posting and scheduling

Client-specific notes

Safe recovery