Model Context Protocol

AirTrail includes a remote Model Context Protocol server. MCP clients can use it to read and manage AirTrail data with the same permissions as the connected user.

ConnectCopy Anchor Link

Use your AirTrail instance's MCP endpoint:

https://your-instance.example/api/mcp

The server uses the Streamable HTTP transport. In clients that support remote MCP and OAuth, adding this URL is enough. The client discovers AirTrail's OAuth endpoints, opens the consent screen, and stores the resulting tokens.

A typical client configuration looks like this:

{
  "mcpServers": {
    "airtrail": {
      "url": "https://your-instance.example/api/mcp"
    }
  }
}

The exact configuration format depends on the MCP client.

AuthenticationCopy Anchor Link

OAuth is the recommended option. AirTrail supports dynamic client registration, the authorization code flow with PKCE, refresh tokens, and protected-resource discovery. The consent screen pre-selects exactly the scopes the client requested. The user can approve those, widen the grant to anything else their role allows, or narrow it further before approving.

Clients without OAuth support can use a personal API key. Create one under Settings → Security → API Keys, select only the scopes the client needs, and send it as a bearer token:

{
  "mcpServers": {
    "airtrail": {
      "url": "https://your-instance.example/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Never put an API key in a shared configuration file or commit it to source control.

Permissions and scopesCopy Anchor Link

Every operation must pass two checks:

1. The user's current AirTrail role must permit the action.
2. The OAuth grant or API key must include the required scope.

The credential can narrow a user's access, but cannot grant permissions that the user does not have. Changes to the user's role take effect on later MCP calls without requiring a new credential.

Available toolsCopy Anchor Link

Clients receive the complete tool names, descriptions, input schemas, and destructive-action annotations during MCP initialization. AirTrail also publishes the connected profile as the airtrail://profile resource.

Each tool performs the same operation as its REST endpoint, requires the same scopes, and returns the same data. The flight list, export, and statistics tools take the REST scope (mine, user, or all) and userId arguments. Flight listings use cursor pagination: pass the returned page.nextCursor value unchanged as cursor on the next call. A null cursor means there are no more pages.

HTTP discovery and transport behaviorCopy Anchor Link

The endpoint accepts cross-origin requests, so browser-based MCP clients can connect; it authenticates from the Authorization header only and never uses cookies.

A regular GET /api/mcp request returns a public JSON document with the endpoint URL, transport, authentication metadata, API discovery URL, and this documentation URL. The API discovery document is available at both /api and /api/v1.

The MCP server is stateless and returns JSON responses to MCP requests sent with POST. It does not provide the optional standalone Server-Sent Events channel. MCP clients that request that channel with Accept: text/event-stream receive 405 Method Not Allowed, as defined by the Streamable HTTP transport. Session deletion is not needed and DELETE also returns 405 after authentication.

OAuth clients can discover authorization metadata at:

https://your-instance.example/.well-known/oauth-protected-resource/api/mcp