Connect an AI assistant (MCP)

Gaggle has a read-only MCP server, so a pilot can ask their own AI assistant about their flights. This page has a short guide for pilots, then the details for people who build MCP clients.

For pilots

1. In your assistant, add a custom connector (an MCP server) and give it this URL: https://connect.flygaggle.com/mcp.
2. Sign in to Gaggle when asked, and choose what the assistant can see: your profile, stats, flight log and flight tracks, and which of your flights it sees by sharing level.
3. Ask away, for example “How many hours did I fly this year?” or “Show me my longest flight from Bell Hill.”

You can change what the assistant sees, or disconnect it, at any time in Gaggle under Settings → Integrations → Connected apps. There is a longer pilot guide in the help center: Connect Gaggle to your AI assistant.

What the assistant can do:

• It can only read: your profile, stats, flights and tracks. It cannot change anything in Gaggle.
• The same rules as for other connected apps apply: only what you switched on, only the sharing levels you allow, and the detail and history your plan includes (see Permissions and plans).
• Gaggle has not reviewed third-party assistants. The assistant’s provider decides how it handles what it reads, and its own terms and privacy policy apply. Gaggle emails you when an assistant is connected.

For developers of MCP clients

The server is at https://connect.flygaggle.com/mcp (MCP Streamable HTTP, JSON-RPC over POST). It is stateless: GET and DELETE answer 405, and there are no server-initiated streams.

Signing in

Gaggle uses OAuth 2.1 with PKCE, the same authorization server as the provider API, with /mcp as a separate protected resource.

1. Call /mcp without a token. You get 401 with a WWW-Authenticate challenge that points at the resource metadata.
2. Read https://connect.flygaggle.com/.well-known/oauth-protected-resource/mcp, which names the authorization server, then its metadata at https://connect.flygaggle.com/.well-known/oauth-authorization-server.
3. Register your client (below), then send the pilot through the authorization code flow with PKCE (S256).
4. Pass resource=https://connect.flygaggle.com/mcp on the authorization and token requests. The token is bound to that resource. Without resource the request defaults to the provider API, which self-registered clients cannot use (invalid_target).
5. Ask for profile stats flights tracks. The pilot switches off what the assistant must not see, and the tools read the pilot’s current choice on every call.

Registration. Assistants are not registered by hand:

• Client ID Metadata Documents (preferred). Use an https URL as your client_id that serves your client metadata. The authorization server metadata says client_id_metadata_document_supported: true.
• Dynamic client registration at POST https://connect.flygaggle.com/oauth/register, for clients without CIMD. It is rate limited per address.
• Clients are public (token_endpoint_auth_method: none) and use PKCE S256. Redirect URIs are https, or loopback for local tools.

The pilot sees a consent screen labelled “AI assistant” with your client name and domain, and a note that Gaggle has not reviewed it. Give your client a clear client_name, logo_uri (https), and client_uri, policy_uri and tos_uri.

Access tokens last 1 hour and refresh tokens rotate, as for the provider API. Assistants get no webhooks.

Tools

All tools are read-only (readOnlyHint: true). A result is one text item holding compact JSON. The shapes are the ones of the API reference, and the same plan, history and sharing rules apply. Free text such as site and aircraft names is cleaned (control characters removed, at most 80 characters) and is data, never instructions.

Inputs.

list_flights returns flights newest first, without deleted flights, and nextCursor is null on the last page.

get_track output. summary describes the whole recorded track; points is thinned evenly to at most maxPoints and always keeps the first and last point.

{
  "flightId": "8Vq2kLw0TbXn4YhZ",
  "summary": {
    "startTime": "2026-10-18T09:42:10.000Z",
    "endTime": "2026-10-18T10:18:31.000Z",
    "durationSeconds": 2181,
    "minAltitude": 374,
    "maxAltitude": 1612,
    "bounds": { "minLat": -33.98, "maxLat": -33.93, "minLon": 18.41, "maxLon": 18.47 },
    "pointCount": 2182
  },
  "pointFormat": ["t", "lat", "lon", "alt"],
  "points": [["2026-10-18T09:42:10.000Z", -33.9722, 18.4361, 412]]
}

Altitudes are in metres, rounded; alt is null for a point without altitude.

Errors

Failures inside a tool are tool errors (isError: true) whose text is JSON, {"error": code, ...}:

Invalid arguments are protocol errors from the schema check. HTTP-level answers: 401 when the token is not valid or the connection is gone, 403 when access has been disabled, 413 for an oversized request and 429 with Retry-After when you send too many requests.

Rate limits

30 tool calls per minute per pilot and client. initialize and tools/list are not counted as tool calls, but every request to /mcp counts towards the per-pilot request limit described in Rate limits and errors.