MCP troubleshooting

Check connection/startup → API communication → token scopes → tool inputs. Never paste raw tokens into logs or agent conversations.

Server does not start

Check	Action
Node not found	Install Node.js 22+ and use the executable's absolute path in command
dist/index.js missing	Run npm ci and npm run build in the MCP repository, then check args
Invalid OPENTESTER_API_URL	Use an absolute HTTPS URL ending in /api/v1, without credentials, query, or fragment
Invalid OPENTESTER_APP_ID	Use the console's app UUID, not its name or package name
Invalid OPENTESTER_AGENT_TOKEN	Use an app agent token, not an SDK token or web cookie

Local MCP does not load .env automatically. The host must pass all three variables to its child process. If only a desktop app fails, compare its environment and PATH with the terminal.

Tools do not appear

Check codex mcp list, claude mcp list, or /mcp in the client. Reconnect after editing configuration.

For hosted HTTP, use https://mcp.opentester.app/mcp and both app authentication headers from the client guide. For local stdio, use the executable configuration instead of an HTTP URL. Neither mode uses MCP OAuth login.

Package 0.1.0 uses MCP SDK v2 entry points and supports current and 2025-style initialization clients. If initialization differs, check both host and server versions.

Tool error codes

API and transport failures set isError: true. Example structuredContent:

{
  "error": {
    "code": "forbidden",
    "message": "This token cannot perform this action for this app. Check its scopes and app ownership.",
    "status": 403
  }
}

status appears only when an HTTP response was received. Errors use fixed messages instead of forwarding the raw API error body.

Code	Cause and action
invalid_request	Check UUIDs, string lengths, duplicate report IDs, and supported fields
unauthenticated	Invalid, expired, or revoked token; issue a new one and reconnect
forbidden	Check app scope, token scopes, ownership, and configured app ID
not_found	Recheck actual report or request IDs in the target app
conflict	Request ID reused with different content or a different PR already linked; inspect existing work
request_too_large	Shorten descriptions or split work
rate_limited	Wait before retrying
api_unavailable	Check service status and retry
timeout	API took over 15 seconds; a write may have succeeded, so reuse ID and input
connection_failed	Check API URL, availability, and network
redirect_refused	Configure the final API URL directly
response_too_large	Response exceeds 4 MiB; reduce list limit
invalid_response	Empty or non-object JSON response; check for login/proxy pages
internal_error	Unexpected failure; check environment and service health

Input validation may reject a call before the API is contacted. Check tool inputs first.

Reads succeed but creation fails

feedback:read permits only feedback reads. Change request reads require work-items:read; creation and PR linking require work-items:write. Issue a new token with the required scopes, replace the environment value or HTTP credential, and reconnect.

No response after creating work

The work may already exist. Retry with the same clientRequestId and original input. A new ID creates separate work even with identical content. This ID is not an agent assignment or locking mechanism; inspect existing requests before starting.

Feedback stays open after linking a PR

This is expected. The request becomes pr_linked, but feedback is not marked fixed. GitHub status synchronization and Play deployment are not included. Manage feedback in the console after testing and deployment.

Redirects and local networks

MCP refuses API redirects so tokens are not forwarded to another address. Configure the final HTTPS URL directly.

Plain HTTP is limited to loopback addresses. LAN addresses such as http://192.168.… and public hosts require HTTPS.