MCP troubleshooting

Check the public service, discovery, OAuth, account surface, and tool authorization in that order.

1. Verify the correct hostname and path

REST API:          https://api.example.com
MCP origin:        https://mcp.example.com
Member endpoint:   https://mcp.example.com/mcp

Common mistakes:

• using api. instead of mcp.;
• using /docs or /api-docs instead of an MCP endpoint;
• authorizing while the wrong member account is active in the browser;
• putting a token or API key in the URL;
• connecting through another customer's hostname.

2. Check public health and readiness

curl --fail --show-error "https://mcp.example.com/health"
curl --fail --show-error "https://mcp.example.com/ready"

/health proves the process responds. /ready should be used for dependencies such as OAuth state storage and durable storage. A service can be alive but intentionally not ready.

3. Check DNS and TLS

curl --head "https://mcp.example.com/"
openssl s_client -connect mcp.example.com:443 -servername mcp.example.com

Confirm the public DNS address, certificate hostname, full chain, expiry, and SNI. ChatGPT and Claude connect from their cloud networks, so a local-only success does not prove remote reachability.

4. Check OAuth discovery

Member metadata:

curl --fail --show-error \
  "https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

Authorization server:

curl --fail --show-error \
  "https://mcp.example.com/.well-known/oauth-authorization-server"

The returned issuer and endpoint URLs must use the same verified customer MCP origin. Reverse proxies must preserve the correct host and HTTPS scheme.

5. Reconnect the client

For ChatGPT, remove and recreate the plugin if discovery or OAuth metadata was cached. Follow Connect ChatGPT.

For Claude Code:

claude mcp list
claude mcp get nexus

Open /mcp, clear authentication, and authorize again. Reauthorization is expected after token revocation, session expiry, tenant change, account-type change, or identity drift.

6. Confirm identity and permissions

Ask the connected client:

Call nexus_whoami and show tenant, identity type, modules, scopes, and available/catalog counts. Do not change anything.

Interpret missing tools as an authorization signal, not necessarily a discovery bug:

• member tools require the /mcp surface and live member menu access;
• reads require nexus:read;
• changes require nexus:write plus confirmation;
• uploads require nexus:upload in addition to write;
• durable scheduled tasks require offline_access.

7. Understand common statuses

Result	Meaning	Action
400 Bad Request	Invalid protocol, OAuth, redirect, resource, tool arguments, or contract	Correct the request; do not retry unchanged
401 Unauthorized	Missing/expired/revoked token, wrong resource, or session must be reauthorized	Reconnect through OAuth
403 Forbidden	Role, module, scope, ownership, sensitive-route policy, DLP, or confirmation denial	Inspect identity/contract; never weaken checks blindly
404 Not Found	Missing or inaccessible object; ownership is deliberately not disclosed	Verify the ID and connected account
409 Conflict	State, idempotency, approval, token rotation, or concurrent-change conflict	Reload state and prepare again
421 Misdirected Request	Host is not a valid enabled customer MCP domain	Use the exact customer's mcp. hostname
429 Too Many Requests	OAuth, MCP, or operation quota exceeded	Respect retry guidance and use backoff
503 Service Unavailable	OAuth/durable storage or another required dependency is unavailable	Fix readiness before accepting traffic
Timeout/TLS failure	DNS, firewall, proxy, TLS, or cloud reachability problem	Test externally and verify certificate/SNI

8. Tool-specific checks

Campaign not found

A campaign that does not exist and one owned by another advertiser return the same result. Confirm the member connection and CID; do not probe other IDs.

Counts are incomplete

Read sourcePagination.complete, exactness flags, and nextOffset. Follow pagination or narrow filters before claiming an account-wide total.

Write will not execute

Confirm that:

1. the OAuth session has the required write scope;
2. current state was read;
3. the exact contract-valid payload was prepared;
4. the displayed diff was explicitly approved;
5. the approval/fingerprint matches the unchanged payload;
6. a unique idempotency key is supplied;
7. a conflicting later change has not invalidated the preview.

Scheduled task is blocked

Reconnect with offline_access, then prepare the constrained task again. The server does not accept arbitrary code or arbitrary API calls as schedules.

9. Inspect logs safely

For a systemd deployment:

journalctl -u nexus-mcp.service -n 100 --no-pager

Look for request ID, verified hostname, route, status, OAuth/session category, dependency readiness, and redacted error context. Never copy authorization headers, cookies, tokens, request bodies, provider URLs with credentials, or database secrets into support messages.

Browser checks

Opening /mcp in a browser is not a complete MCP test. It does not perform client discovery, PKCE, OAuth code exchange, MCP initialization, or tool calls. Use the client connection flow and the discovery/readiness checks above.