# Fly — how to use (mcp.ai)

Connect your Fly account and use 45 tools for developer tools straight from your AI agent. Connect with your own API key. Fly.io transforms containers into micro-VMs that run on hardware in 30+ regions on six continents.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_fly?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `fly_add_wire_guard_peer`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/fly`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/fly/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/fly/add/wire/guard/peer` — Tool to add a WireGuard peer connection to a Fly.io organization for private network access. Use when setting up VPN access or private networking between your infrastructure and Fly.io.
  - body: { name: string, pubkey: string, region?: string, network?: string, organization_id: string }
- `POST https://api.mcp.ai/api/fly/check/app/name/availability` — Tool to validate an app name for Fly.io app creation. Use when you need to check if a proposed app name is available before attempting to create a new app. Returns availability status via GraphQL quer
  - body: { name: string }
- `POST https://api.mcp.ai/api/fly/check/jobs` — Execute GraphQL queries against the Fly.io checkJobs endpoint. Retrieves check jobs with their schedules, URLs, and configuration. Supports pagination via first/last/after/before parameters. Returns b
  - body: { query: string, variables?: object }
- `POST https://api.mcp.ai/api/fly/check/user/only/token` — Check whether the authentication token only allows user access. Returns false if the token allows organization access, true if it only allows user access.
- `POST https://api.mcp.ai/api/fly/create/check/job` — Tool to create a health check job for monitoring application endpoints in Fly.io. Use when you need to set up automated health monitoring for a URL from multiple geographic locations.
  - body: { url: string, locations: string[], http_options: object, organization_id: string }
- `POST https://api.mcp.ai/api/fly/create/check/job/run` — Triggers a run of an existing health check job on Fly.io. Use when you need to manually trigger a health check for monitoring or testing purposes.
  - body: { check_job_id: string }
- `POST https://api.mcp.ai/api/fly/create/delegated/wire/guard/token` — Tool to create a delegated WireGuard token for peer management in a Fly.io organization. Use when you need to generate a token for managing WireGuard peers with delegated access.
  - body: { name?: string, organization_id: string, client_mutation_id?: string }
- `POST https://api.mcp.ai/api/fly/create/third/party/configuration` — Tool to create a third-party service configuration for discharging macaroon caveats. Use when you need to configure external authorization services for Fly.io token validation.
  - body: { name: string, caveats?: string, location: string, uiexLevel: string, customLevel: string, flyctlLevel: string, organizationId: string, clientMutationId?: string }
- `POST https://api.mcp.ai/api/fly/delete/delegated/wire/guard/token` — Tool to delete a delegated WireGuard token from a Fly.io organization. Use when you need to revoke or remove an existing WireGuard token that was previously created. Either token or name must be provi
  - body: { name?: string, token?: string, organization_id: string, client_mutation_id?: string }
- `POST https://api.mcp.ai/api/fly/delete/organization` — Tool to delete a Fly.io organization and all its associated resources using the GraphQL API. Use when you need to permanently remove an organization. This operation is irreversible.
  - body: { organizationId: string, clientMutationId?: string }
- `POST https://api.mcp.ai/api/fly/delete/remote/builder` — Tool to delete a remote builder configuration for a Fly.io organization. Use when you need to remove the remote builder setup from an organization.
  - body: { organization_id: string, client_mutation_id?: string }
- `POST https://api.mcp.ai/api/fly/delete/third/party/configuration` — Tool to delete a third-party service configuration from Fly.io. Use when you need to remove an existing third-party service integration or configuration that was previously created.
  - body: { client_mutation_id?: string, third_party_configuration_id: string }
- `POST https://api.mcp.ai/api/fly/detach/postgres/cluster` — Tool to detach a Postgres cluster from a Fly.io application, revoking access credentials. Use when you need to remove database connectivity from an application.
  - body: { app_id: string, client_mutation_id?: string, postgres_cluster_app_id: string, postgres_cluster_attachment_id?: string }
- `POST https://api.mcp.ai/api/fly/establish/ssh/key` — Tool to establish an SSH key for a Fly.io organization. Use when setting up SSH access for secure connections to Fly.io infrastructure.
  - body: { override?: boolean, organization_id: string, client_mutation_id?: string }
- `POST https://api.mcp.ai/api/fly/fetch/nodes/by/ids` — Fetches a list of node objects from Fly.io given a list of IDs using the GraphQL nodes query. Use when you need to retrieve multiple objects by their IDs in a single request. Supports all Node interfa
  - body: { ids: string[], query_fields?: string }
- `POST https://api.mcp.ai/api/fly/get/add/on` — Tool to find a Fly.io add-on by ID, name, or provider. Use when you need to retrieve details about a specific add-on. Returns add-on information including status, organization, region, and access URLs
  - body: { id?: string, name?: string, provider?: string }
- `POST https://api.mcp.ai/api/fly/get/add/on/provider` — Tool to query information about a specific Fly.io add-on provider (extension) by name. Returns provider details including provisioning settings, terms of service, and configuration options.
  - body: { name: string }
- `POST https://api.mcp.ai/api/fly/get/app/details` — Tool to retrieve detailed information about a specific Fly.io application. Use when you need to get app details including certificates and configuration.
  - body: { name: string }
- `POST https://api.mcp.ai/api/fly/get/certificate` — Tool to retrieve a certificate by its ID from Fly.io. Use when you need to get details about a specific certificate including hostname, creation date, and configuration status.
  - body: { certificate_id: string }
- `POST https://api.mcp.ai/api/fly/get/current/token/info` — Tool to get information about the current authentication token. Use when you need to retrieve details about the token being used for API authentication, including organizations, apps, and whether the 
- `POST https://api.mcp.ai/api/fly/get/latest/image/details` — Tool to retrieve the latest available tag details for a given image repository from Fly.io's registry. Use when you need to get digest, registry, repository, tag, and version information for a contain
  - body: { image: string, fly_version?: string }
- `POST https://api.mcp.ai/api/fly/get/latest/image/tag` — Tool to retrieve the latest available image tag for a Fly.io Docker repository. Use when you need to find the most recent version of a Fly.io image.
  - body: { repository: string }
- `POST https://api.mcp.ai/api/fly/get/machine` — Tool to get a single machine by ID from Fly.io. Use when you need to retrieve details about a specific machine instance.
  - body: { machineId: string }
- `POST https://api.mcp.ai/api/fly/get/nearest/region` — Tool to retrieve the nearest Fly.io region to the requesting client based on network location. Use when you need to determine which Fly.io region has the lowest latency from the current location.
- `POST https://api.mcp.ai/api/fly/get/node` — Tool to fetch an object by its globally unique ID using Fly.io's GraphQL node query. Returns a Node interface object with id and __typename fields. Use when you need to retrieve any Fly.io object by i
  - body: { id: string }
- `POST https://api.mcp.ai/api/fly/get/organization` — Tool to find a Fly.io organization by slug using the GraphQL API. Use when you need to retrieve organization details including ID, name and slug.
  - body: { slug: string }
- `POST https://api.mcp.ai/api/fly/get/personal/organization` — Tool to retrieve the user's personal organization details from Fly.io. Use when you need to check credit balance, saved payment methods, certificates, or WireGuard peer information.
- `POST https://api.mcp.ai/api/fly/get/placements` — Tool to get placement recommendations for Machines in Fly.io regions. Use when you need to determine optimal regions for deploying machines based on resource requirements, volume constraints, and orga
  - body: { count?: integer, region?: string, compute?: object, weights?: object, org_slug: string, volume_name?: string, volume_size_bytes?: integer }
- `POST https://api.mcp.ai/api/fly/get/platform/info` — Tool to retrieve Fly.io platform information including available regions, VM sizes, and flyctl version. Use when you need infrastructure-level details about the Fly.io platform.
- `POST https://api.mcp.ai/api/fly/get/products` — Tool to retrieve Fly.io product and price information via GraphQL. Use when you need to fetch product catalog, pricing tiers, or billing information.
- `POST https://api.mcp.ai/api/fly/get/regions` — Tool to get the list of available Fly.io regions with optional filtering. Use when you need to discover which regions are available for deploying machines, or to filter regions by specific resource re
  - body: { cpus?: integer, gpus?: integer, size?: string, cpu_kind?: string, gpu_kind?: string, memory_mb?: integer }
- `POST https://api.mcp.ai/api/fly/get/viewer/info` — Tool to retrieve the authenticated user's account information from Fly.io. Use when you need to get the current user's profile details, including avatar, email, creation date, and feature flags.
  - body: { query?: string }
- `POST https://api.mcp.ai/api/fly/issue/certificate` — Tool to issue an SSH certificate for accessing Fly.io infrastructure. Returns an SSH certificate in OpenSSH format. Use when you need to authenticate SSH access to Fly.io machines or apps.
  - body: { app_names?: string[], principals?: string[], public_key?: string, valid_hours?: integer, organization_id: string, client_mutation_id?: string }
- `POST https://api.mcp.ai/api/fly/list/add/on/plans` — Tool to list available add-on service plans from Fly.io. Use when you need to discover pricing, features, and resource limits for Fly.io add-on services. Supports cursor-based pagination.
  - body: { last?: integer, after?: string, first?: integer, before?: string }
- `POST https://api.mcp.ai/api/fly/list/add/ons` — Tool to list add-ons associated with an organization in Fly.io. Use when you need to retrieve add-ons for apps in an organization. Supports querying personal organization or specific organizations by 
  - body: { query?: string, variables?: object }
- `POST https://api.mcp.ai/api/fly/list/apps` — Tool to list all Fly Apps in an organization. Use when you need to retrieve apps for a specific organization using its slug.
  - body: { app_role?: string, org_slug: string }
- `POST https://api.mcp.ai/api/fly/list/apps/graphql` — List all Fly.io applications with details including volumes, services, and VMs using GraphQL. Use when you need to retrieve a comprehensive overview of all apps in your Fly.io organization.
  - body: { last?: integer, after?: string, first?: integer, before?: string, include_vms?: boolean, include_volumes?: boolean, include_services?: boolean }
- `POST https://api.mcp.ai/api/fly/list/check/locations` — Retrieve all available Fly.io health check locations. Returns a comprehensive list of global locations where health checks can be performed, including geographic details and coordinates. Use when you 
- `POST https://api.mcp.ai/api/fly/list/machines` — Tool to list Fly.io machines using GraphQL API with pagination support. Use when you need to retrieve information about deployed machines including their state, region, and creation time.
  - body: { last?: integer, after?: string, first?: integer, before?: string }
- `POST https://api.mcp.ai/api/fly/list/org/machines` — Tool to list all Machines across all apps in a Fly organization. Use when you need to retrieve machines for monitoring, management, or inventory purposes. Supports filtering by region, state, and time
  - body: { limit?: integer, state?: string, cursor?: string, region?: string, org_slug: string, updated_after?: string, include_deleted?: boolean }
- `POST https://api.mcp.ai/api/fly/remove/wire/guard/peer` — Tool to remove a WireGuard peer connection from a Fly.io organization. Use when you need to delete or revoke an existing WireGuard peer from your organization's network.
  - body: { name: string, organization_id: string }
- `POST https://api.mcp.ai/api/fly/set/apps/v2/default/on` — Tool to configure whether new apps in an organization use Apps V2 by default on Fly.io. Use when you need to enable or disable Apps V2 as the default for new applications in a specific organization.
  - body: { default_on: boolean, organization_slug: string }
- `POST https://api.mcp.ai/api/fly/update/third/party/configuration` — Tool to update an existing third-party service configuration for discharging macaroon caveats. Use when you need to modify settings of external authorization services for Fly.io token validation.
  - body: { name?: string, caveats?: string, location?: string, uiexLevel?: string, customLevel?: string, flyctlLevel?: string, clientMutationId?: string, thirdPartyConfigurationId: string }
- `POST https://api.mcp.ai/api/fly/validate/config` — Tool to validate a Fly.io app configuration. Use when you need to check if a fly.toml configuration is valid before deploying or updating an app.
  - body: { definition: object }
- `POST https://api.mcp.ai/api/fly/validate/wire/guard/peers` — Tool to validate WireGuard peer IP addresses in a Fly.io organization. Use when you need to verify which peer IPs are valid or invalid before establishing VPN connections.
  - body: { peer_ips: string[] }

## Example prompts
- "What can I do in Fly?"
- "Show me a summary of my Fly account"

## More
- Page: https://mcp.ai/fly
- Agent spec (llms.txt): https://mcp.ai/fly/llms.txt
- Postman collection: https://mcp.ai/fly/postman.json