# The Fly MCP: verified setup for agents and people

These are this deployment’s public connection facts. This guide is available without JavaScript or sign-in. The JSON contract is a The Fly documentation format, not a new MCP discovery standard.

## Exact endpoint and transport

- Full MCP endpoint: https://mcp.thefly.com/mcp
- Transport: Streamable HTTP (not SSE or stdio).
- Preferred API-key header: X-API-Key: <MCP API key>.
- Compatibility: Authorization: Bearer <MCP API key> is also accepted by the full endpoint. Send one credential header, never both. Do not guess paths or put credentials in a URL.
- ChatGPT app endpoint: https://mcp.thefly.com/chatgpt/mcp (OAuth only, compact read-only profile; no API keys).

## Choose the correct account and authentication path

For an existing The Fly user: https://mcp.thefly.com/dev/login then https://mcp.thefly.com/dev/keys. Keep existing working keys. A masked preview is not a usable key; never replace a key without explicit approval. Sign-in, MFA and consent stay under human control.

### Claude web / native Claude Desktop connector

Use the full endpoint above in Claude’s custom connector. Leave Advanced OAuth Client ID and Client Secret blank; Claude performs dynamic client registration and Authorization Code + PKCE S256. Complete human The Fly sign-in and consent. This path does not take an API key in the advanced OAuth fields. Local/manual Desktop bridges are a different setup and do not sync into the hosted connector.

OAuth configuration present: true. Check https://mcp.thefly.com/readyz for current readiness; configuration presence is not a successful login. Do not use an upstream Auth0 token as an MCP bearer.

### Claude Code (API-key path)

After the user approves local configuration, merge—not overwrite—this valid JSON into .mcp.json. Provision THEFLY_MCP_API_KEY locally through the user’s approved secret/environment mechanism; never request or paste its value in chat. The literal placeholder below is Claude Code environment substitution, not a universal client syntax.

```json
{
  "mcpServers": {
    "thefly": {
      "type": "http",
      "url": "https://mcp.thefly.com/mcp",
      "headers": {
        "X-API-Key": "${THEFLY_MCP_API_KEY}"
      }
    }
  }
}
```

Cursor, scripts and other header-capable clients use the same endpoint and X-API-Key header with their own secure configuration syntax. Interactive OAuth is an alternative when supported; never invent client credentials.

### New standalone agent account (optional, approval required)

Do not create an account silently or recreate an existing human account. Only after explicit user approval, POST https://mcp.thefly.com/dev/api/signup with JSON fields email (approved contact email), password (generated and stored locally, at least 10 characters), label and agent:true. Retain the returned generated agent email; it is distinct from the human/Auth0 identity and does not inherit their subscription or personal data. New accounts have no API keys. The returned portal_credential manages the account; it is not an MCP key. To create a key after explicit approval, POST https://mcp.thefly.com/dev/api/keys/create with api_key set to that portal_credential and an optional label. Save the newly returned one_time_secret.secret directly to the approved secret store and use its mcp_url/auth_header. The new secret is shown once. Alternatively use Create key on the developer keys page. Do not echo passwords, portal credentials or API keys in a conversation. No purchase or upgrade is part of setup.

## Verify, without changing customer data

1. Use the client SDK to initialize and complete the MCP handshake, then tools/list.
2. With user approval, run one harmless read-only tool, such as search_symbols for AAPL.
3. Report the endpoint, authentication type, non-secret config location and test outcome; never report a credential value.
The full profile may include OAuth-scoped watchlist/preference mutations. Initialization and discovery are not permission to execute them.

## Report problems

Tool: `submit_feedback`. After finishing your task, report once per distinct problem: a tool error, wrong, stale or empty data, a missing tool or parameter, or a confusing description. Improvement ideas are welcome.

- Fields: kind (bug, tool_gap, data_quality, docs, suggestion, other), summary (10-200 characters), optional details, tool_name, severity (low, medium, high) and client.
- Limits: Works with an API key or OAuth. Up to 20 reports per account per UTC day. It does not use normal tool quota. Reports are kept for 180 days.
- Safety: Never include API keys, tokens, passwords or personal data. Obvious secrets and email addresses are redacted, but do not rely on that.

## Troubleshooting

- Consent session or CSRF validation failed: start one fresh authorization from the client in the same browser. Close stale consent tabs; do not refresh or resubmit the failed page. Leave native Claude advanced OAuth fields blank. Do not bypass CSRF or disable browser security.
- Collect client surface/version, browser, exact time/time zone and error-only screenshot. Do not send authorization URLs, cookies, headers, form bodies or HAR exports.
- HTTP 401: verify endpoint and credential type. Missing or rejected credentials are not a reason to rotate a working key automatically.
- HTTP 429: respect Retry-After and account quotas; reconnecting or replacing keys is not a quota workaround.

## Public discovery links

- [Human documentation](https://mcp.thefly.com/)
- [Machine-readable manifest and agent_setup contract](https://mcp.thefly.com/MANIFEST.json)
- [Agent index](https://mcp.thefly.com/llms.txt)
- [OAuth authorization server metadata](https://mcp.thefly.com/.well-known/oauth-authorization-server)
- [Full endpoint protected-resource metadata](https://mcp.thefly.com/.well-known/oauth-protected-resource)
- [ChatGPT protected-resource metadata](https://mcp.thefly.com/.well-known/oauth-protected-resource/chatgpt/mcp)
