Debugging
Most problems with the MCP connector fall into three buckets: the connection never completed, the tokens expired, or a tool call failed. This page covers each.
”I can’t connect”: the OAuth flow failed
Symptom: You add the server URL and either don’t get redirected, get redirected and see an error, or come back to the client without an enabled connector.
Try:
- Confirm the server URL is exactly
https://mcp.traveler.md/mcp, including the/mcppath. - Confirm you’re signed in to TravelAI in the same browser. If your client opens an in-app browser, sign in there first.
- Check the consent screen. If you denied any scope, the client will treat the connection as failed. Restart and approve all requested scopes.
- If you’re on a corporate network, OAuth redirects can be blocked. Try a personal network briefly to isolate.
If you still can’t connect, see Support.
”It worked yesterday”: token expired or revoked
Symptom: The agent says something like “I lost access to your travel preferences.” You see HTTP 401 or an UNAUTHORIZED tool error in client logs.
This usually means:
- Your refresh token expired (90 days of inactivity).
- The connection reached its one-year lifetime cap. This one arrives regardless of how actively you were using it, and the token endpoint says so:
invalid_grantwith a “maximum lifetime” description rather than the plain expiry message. - You revoked the connection from Connections and forgot. Revocation takes effect within a minute, so this can appear in the middle of a session.
- The client’s stored token was wiped (signed out, reinstalled, etc).
- The client presented a refresh token it had already exchanged. Rotation is strict: replaying a spent refresh token ends the connection. This is worth ruling out first if the disconnect followed a crash, a network timeout mid-refresh, or two copies of the client running at once.
Fix: Reconnect from your client’s connector settings. The OAuth flow will issue fresh tokens.
”The tool call failed”: agent saw an error
Symptom: The agent tried to call read_profile or another tool and got an error back.
A failed tool call returns a tool result with isError: true. The error code is in structuredContent.error.code:
| Code | Meaning | What to do |
|---|---|---|
UNAUTHORIZED | The traveler revoked the connection or narrowed its scopes after consent. The message is “Authorization has been revoked” or “Scope no longer granted: <scope>”. | Reconnect the connector and approve the scope again. |
FORBIDDEN | The token’s scopes never included the scope (“forbidden: missing scope <scope>”), or the traveler withheld a section from this client (details.disallowedSections). | For a missing scope, reconnect and grant it. For a withheld section, retry without it, or ask the traveler to add it to this client’s access. |
NOT_FOUND | The trip does not exist, is not visible to this client, or is already archived. | Check list_trips again. It hides archived trips. A missing Traveler.md is not this error: read_profile succeeds with a null version_hash, which is the signal to create the profile. |
CONFLICT | Another write happened since your last read, the profile already exists, or a trip slug is already in use. | Read again before you retry. Sections are replaced wholesale, so the same body sent with the current hash overwrites the other writer. A slug collision names no hash and needs a different slug or title. |
VALIDATION_ERROR | An unknown section name, a section over its sentence cap, an empty section without allow_clear_sections, rejected sensitive data, an invalid cursor, or an end_date before the start_date. | The message names the fields. For a cap, send fewer sentences: the cap applies to the whole section you send. To empty a section on purpose, resend with allow_clear_sections: true. |
IDEMPOTENCY_MISMATCH | The idempotency_key “has already been used with a different request body”. | Send the original body again, or use a new key for a different call. |
IDEMPOTENCY_IN_PROGRESS | Another request with the same idempotency_key is still running. | Wait, then retry with the same key and body. |
SERVICE_UNAVAILABLE | A temporary server problem. | Retry after a short wait. |
INTERNAL | An unexpected server error. | Contact support. |
Some rejections happen at the HTTP transport, before any tool runs:
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | UNAUTHORIZED | The access token is missing or invalid. | Refresh the token. If that fails, reconnect the connector. |
| 429 | RATE_LIMITED | Too many calls in a short window. | Wait for the time in the retry-after header. x-ratelimit-* headers give the limit. |
| 503 | SERVICE_UNAVAILABLE | A server instance is shutting down, or rate limits cannot be checked. | Retry after the retry-after header (2 seconds). |
Inspecting your data
You can always see exactly what the server has stored by signing in at app.traveler.md and viewing your Traveler.md and any Trip.md files. If something an agent wrote looks wrong, this is where to confirm it.
Write history
Every write is versioned. Open Activity in the app sidebar for a log of every edit to your Traveler.md and trips. Each entry shows what changed, when, and which connected app made the change.
There is no one-click revert. Restoring an earlier state is an ordinary write: read the current version, send back the content you want, and it becomes the new version with the old one still in the history.
Still stuck?
See Support for contact paths.