> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocoya.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common Ocoya MCP connection, OAuth, workspace, and tool-call issues.

# 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:

```bash theme={null}
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:

```txt theme={null}
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:

```txt theme={null}
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:

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.