---
title: MCP troubleshooting
description: Resolve OpenTester MCP connection, authentication, scope, and retry issues.
---

# MCP troubleshooting {#mcp-troubleshooting}

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

## Server does not start {#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 {#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](/mcp/clients#remote-http). 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 {#tool-error-codes}

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

```json
{
  "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](/mcp/tools) first.

## Reads succeed but creation fails {#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](/api/tokens) with the required scopes, replace the environment value or HTTP credential, and reconnect.

## No response after creating work {#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 {#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 {#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.