Troubleshooting

MCP errors come from different layers. Check the HTTP status first, then the response body:

• OAuth errors use error and error_description.
• HTTP MCP errors use a Doow error code such as TOKEN_EXPIRED or SESSION_NOT_FOUND.
• Tool failures are returned as an MCP tool result with isError: true.
• Some responses include _meta guidance. It is not present on every error.

Authentication errors

Missing or invalid token

The transport returns HTTP 401. Complete OAuth in your MCP client, or send a valid bearer token:

Authorization: Bearer ACCESS_TOKEN_JWT

OAuth discovery and protected-resource metadata are available at:

https://mcp.doow.co/.well-known/oauth-authorization-serverhttps://mcp.doow.co/.well-known/oauth-protected-resource

Expired or revoked token

Refresh the OAuth token, then initialize a new MCP session. If the token was revoked, run OAuth again. MCP API keys must be replaced or revoked through the authenticated API-key flow.

OAuth errors

OAuth uses standard responses such as:

{"error": "invalid_grant","error_description": "refresh token reuse detected"}

Common causes:

• Missing resource=https://mcp.doow.co in the authorization request
• A code verifier that does not match the challenge
• An authorization code older than 10 minutes
• Reusing an authorization code
• Reusing a rotated refresh token

Use S256 PKCE, keep the same verifier through the exchange, and restart OAuth when a code or refresh-token family is rejected.

Session errors

Session not found or expired

Session failures return HTTP 404 with a Doow error body:

{"error": {  "code": "SESSION_NOT_FOUND",  "message": "Session expired or invalid",  "details": null,  "action": "Initialize a new MCP session"}}

Sessions expire after 60 minutes of inactivity. They are also tied to the access token used to create them. After refreshing an access token, initialize a new session.

Missing session ID

After initialize, send Mcp-Session-Id on every request. A missing or unknown ID is a session error; do not invent a session ID.

Missing Accept header

Send both response formats the Streamable HTTP transport supports:

Accept: application/json, text/event-stream

Tool errors

Tool failures are returned in an MCP result rather than as a top-level JSON-RPC error:

{"isError": true,"content": [  {    "type": "text",    "text": "{"code":"RESOURCE_NOT_FOUND","message":"Resource does not exist"}"  }]}

The text value contains the Doow error object. Use the relevant list or search tool to find valid IDs. A resource outside the member's organization is not exposed as readable data.

Missing scope

The tool requires mcp:write, but the token only has mcp:read. Re-authorize with the required scope, subject to the member's Doow permissions.

Permission denied

Your Doow role does not allow the operation or resource. Ask an organization administrator to change the member's permissions; a valid MCP token does not bypass Doow access rules.

Confirmation errors

Protected tools require client elicitation support. A client without that capability receives CAPABILITY_REQUIRED. A user declining the prompt returns ELICITATION_DENIED; a prompt that times out returns ELICITATION_TIMEOUT.

Interactive clients can handle these prompts. A plain script or codex exec cannot approve a protected operation.

Rate limits

Rate-limited requests return HTTP 429 and include Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers.

The current limits are:

OAuth token exchange and refresh do not currently have a matching MCP-specific limiter. Wait for Retry-After before retrying; preserve the original JSON-RPC request ID when retrying a confirmed operation.

Session cleanup

Clients can close a session with:

DELETE https://mcp.doow.co/mcpMcp-Session-Id: SESSION_ID

Doow returns 204 No Content.

Request size

Requests larger than the transport limit are rejected. Reduce the input, split the operation, or use a smaller file before retrying.

Next steps