# Fly MCP

One MCP for all of Fly.

Bring Fly.io to your AI client. The tools and resources to build, run, and manage your apps and Sprites, right where you work.

## Connect your client

Choose your harness for setup instructions. Each connects to the same Fly MCP server using browser sign-in.

### Claude Code

#### 1. Add Fly MCP

Add the HTTP server to your user configuration so it is available across projects.

```sh
claude mcp add --transport http --scope user fly-mcp https://mcp.fly.io
```

#### 2. Sign in

```sh
claude mcp login fly-mcp
```

Complete the browser sign-in, select your organization, and review the access you are granting.

#### 3. Check the connection

```sh
claude mcp get fly-mcp
```

Check that the server is connected. In Claude Code, open /mcp to inspect its tools and manage the connection.

[Official setup guide](https://code.claude.com/docs/en/mcp)

### Codex

#### 1. Add Fly MCP

```sh
codex mcp add fly-mcp --url https://mcp.fly.io
```

#### 2. Sign in

Complete the browser sign-in opened by Codex. If it does not open, start it with:

```sh
codex mcp login fly-mcp
```

Select your intended organization and review the requested access.

#### 3. Check the connection

```sh
codex mcp list
```

Confirm that fly-mcp is listed, then open /mcp in Codex to inspect the available tools.

[Official setup guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

### Cursor

#### 1. Add the server configuration

Add this server to ~/.cursor/mcp.json. Keep any existing servers in that file.

```json
{
  "mcpServers": {
    "fly-mcp": {
      "url": "https://mcp.fly.io"
    }
  }
}

```

#### 2. Sign in

Open Cursor Settings, then Customize > MCPs. Find fly-mcp and follow its sign-in prompt. Complete browser consent for your intended organization.

#### 3. Use the tools in Agent

Open Agent and check that Fly MCP tools are enabled. Start by asking for the Sprites you can access, and review tool approvals before making changes.

[Official setup guide](https://cursor.com/docs/mcp)

### VS Code

#### 1. Add an HTTP server

Open the Command Palette and run MCP: Add Server. Choose HTTP, enter the URL below, name the server fly-mcp, and choose where to save its configuration.

```text
https://mcp.fly.io
```

#### 2. Start and authorize the server

Run MCP: List Servers, select fly-mcp, and start it. Review the server trust prompt and complete browser sign-in and consent.

#### 3. Enable tools in Copilot

Open Copilot Chat in Agent mode. Use Configure Tools to enable Fly MCP, then ask it to list the Sprites you can access.

[Official setup guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

### Claude web & desktop

#### 1. Add a custom connector

Open Connectors under Customize or Settings. Choose + Add, then Add custom connector, and name it Fly MCP. Use the Claude account where you want the connection available.

#### 2. Enter the server URL

```text
https://mcp.fly.io
```

Continue with the detected OAuth settings. Choose Sign in now and leave custom request headers empty.

#### 3. Complete browser consent

Add the connector and complete sign-in promptly. Select your intended organization and review its access restrictions. Check that the connector reports connected when you return to Claude.

#### 4. Enable it in your conversation

Open the + menu in your chat, choose Connectors, and enable Fly MCP. Remote connectors work on both Claude web and desktop; no local Desktop JSON configuration is needed.

Free accounts are limited to one custom connector. On Team and Enterprise plans, your organization may require an owner or authorized administrator to add the connector before you can connect.

[Official setup guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

### Gemini CLI

#### 1. Add Fly MCP

```sh
gemini mcp add --transport http --scope user fly-mcp https://mcp.fly.io
```

#### 2. Sign in from Gemini

Start Gemini CLI and run this command inside the session. Complete browser sign-in and consent for your organization.

```text
/mcp auth fly-mcp
```

#### 3. Check the tools

```text
/mcp
```

Check the server connection and available tools. Review tool approvals when Gemini asks to use Fly MCP.

[Official setup guide](https://geminicli.com/docs/tools/mcp-server/)

### Antigravity CLI

#### 1. Add Fly MCP

HTTP servers are detected from the URL; no transport flag is needed.

```sh
agy mcp add fly-mcp https://mcp.fly.io
```

#### 2. Sign in from Antigravity

Start Antigravity CLI and open the MCP panel. Choose fly-mcp, then Authenticate, and complete browser sign-in and consent for your organization.

```text
/mcp
```

#### 3. Check the tools

The same panel lists the server's tools once it is connected. Review tool approvals when Antigravity asks to use Fly MCP.

[Official setup guide](https://antigravity.google/docs/cli-overview)

### OpenCode 2

#### 1. Add Fly MCP

These commands are for OpenCode 2.

```sh
opencode mcp add fly-mcp --global --url https://mcp.fly.io
```

[Setup for OpenCode 1.x](https://opencode.ai/docs/mcp-servers/)

#### 2. Sign in

```sh
opencode mcp auth fly-mcp
```

Complete the browser sign-in, choose your organization, and review the requested access.

#### 3. Check the connection

```sh
opencode mcp list
```

Check the connection status, then ask OpenCode to list the Sprites you can access.

[Official setup guide](https://opencode.ai/v2/docs/mcp-servers)

### Other clients

#### 1. Add a remote HTTP server

Choose your client's remote HTTP or Streamable HTTP MCP connection and enter this URL.

```text
https://mcp.fly.io
```

#### 2. Complete OAuth sign-in

Use automatic OAuth discovery and your client's browser sign-in flow. Choose the intended organization and review consent. No custom authorization header or pasted API token is needed.

#### 3. Check the available tools

Confirm that the server connects and its tools appear. Start with listing authorized Sprites, and review your client's tool approval settings before making changes.

[Official setup guide](https://modelcontextprotocol.io/docs/getting-started/intro)

### Choose your access

Sign in through https://fly.io and choose the organizations, existing Fly apps, and Sprites permissions to authorize in one consent screen. The same connection uses both sets of tools. Your client handles OAuth; you do not need to paste an API token.

> Select only the resources and permissions you need. Organization SSO may require its usual verification in the browser.

### Try your first tool

Once connected, try this read-only prompt. Check the organization in the result before asking your client to make changes.

> List the Sprites I can access and show the organization name. Do not create, change, or delete anything.

## Work with Sprites

Sprites provide persistent environments with files, commands, services, checkpoints, and network policies.

- Find authorized Sprites, inspect their metadata, and open the Sprite Inspector in clients that support the MCP Apps UI extension.
- Create and remove Sprites within your grant's restrictions.
- Read and write files, run non-interactive commands, and inspect or stop exec sessions.
- Inspect and manage services, checkpoints, and network policies.

The tool reference below comes from the server's tool definitions. Your grant and the selected Sprite determine which calls are permitted. A listed tool is not permission to use it.

## Start with a small workflow

Try these prompts with your AI client. Replace the example name with a Sprite permitted by your grant.

### Get your bearings

> List the Sprites I can access. Show metadata for the one I select, without waking it or changing anything.

### Try a disposable environment

> Create mcp-demo, write a greeting to /tmp/hello.txt, and read it back. Show me the result, then ask before deleting the disposable Sprite.

### Investigate a service

> Show metadata for my selected Sprite first. Before reading its runtime state or logs, tell me that this may wake it. Summarize what you find and ask before changing a service or restoring a checkpoint.

## Choose the scope of access

Authorize only the organizations, products, and operations you need. New tools appearing in the catalogue do not expand your grant. Client tool approvals are an additional control.

### Current Sprites permissions

Sprites consent ties this connection to an organization and its backing Sprites token. Use the smallest access you need, including the name prefix and Sprite limit available on the consent screen.

- Check the selected organization and Sprite before writing files, running commands, or making service and network changes.
- Deleting a Sprite or file and restoring a checkpoint can discard work. Review the target and intended change before approving those calls.
- To end access, disconnect the client and revoke its backing Sprites token. Revocation prevents further use of that token, including OAuth refresh.

This guide is public. Reading it does not grant access to Fly resources or authorize a tool call.

## Diagnose without surprises

### Start with Sprite metadata

get_sprite_info reads authorized metadata without waking the Sprite. Opening the Sprite Inspector starts with metadata too. Reading selected runtime state, services, logs, or files may wake a Sprite; request those reads deliberately.

Use the current Sprite identity returned by selection or discovery. If a Sprite was deleted and recreated under the same name, select it again instead of reusing its old ID.

### If a connection or call fails

- Cannot connect: check that your account and organization have access and that the URL is https://mcp.fly.io.
- Authentication failed: your client should refresh expiring access automatically. If sign-in still fails or access was revoked, reconnect through consent instead of copying an old token.
- Permission denied or a Sprite is missing: check the consented organization, name prefix, limits, and current Sprite identity. Repeated retries do not expand a grant.
- Backend unavailable: retry a read after service recovers. If a write timed out, inspect its result before repeating it; the first operation may have completed.

When reporting a problem, include your client version, the operation, and the visible error. Keep tokens, authorization codes, and private file contents out of the report.

## Tool reference

The reference includes Fly apps, Machines, volumes, secrets, and Sprites. Names and descriptions come directly from their tool definitions. Ask your client for the current tool schema before constructing arguments.

The same authorization can enable Sprites tools and direct operations on existing Fly apps, Machines, volumes, and app secrets. IP addresses and certificates are read-only. Deployment workflows, app creation, product provisioning, and organization administration are not included.

### Account and context

#### Account and context (4 tools)

##### `get_fly_context`

Show this connection's current authorized resource bindings, per-resource scopes, and restrictions, including the Sprites name_prefix and max_sprites_total creation limit. This describes the grant and never expands access.

##### `list_organizations`

List current organization identities and roles under explicitly granted account-directory access. This does not authorize their resources.

##### `get_organization`

Read the selected organization's identity, current role and launch eligibility.

##### `get_launch_requirements`

Explain launch blockers and return browser handoffs for billing, SSO or provider terms. Does not accept terms or alter payment settings.

### Fly apps and resources

#### Apps (3 tools)

##### `list_apps`

List app identity, organization, status, and counts.

##### `get_app`

Read an app's identity, organization, status, and counts.

##### `delete_app`

Permanently delete the app. This can disrupt or delete its resources; inspect the app first. Requires explicit fly:apps:delete authorization.

#### Machines (28 tools)

##### `list_machines`

List Machine identity and lifecycle summaries for an app. Excludes configuration and secrets.

##### `get_machine`

Read a Machine's identity and lifecycle summary. Excludes configuration and secrets.

##### `get_machine_configuration`

Read the full Machine configuration under explicit authorization. Configuration can contain sensitive environment, file and metadata values. Requires explicit fly:machines:sensitive:read authorization.

##### `create_machine`

Create a billable Machine from explicit configuration. It starts unless skip_launch is set. If the response is lost, inspect existing Machines before retrying; mutations are not automatically retried. Requires explicit fly:machines:write authorization.

##### `delete_machine`

Permanently destroy the Machine and its ephemeral root filesystem. Attached volumes are separate resources. force is never enabled implicitly. Requires explicit fly:machines:delete authorization.

##### `start_machine`

Start Machine. Requires explicit fly:machines:write authorization.

##### `stop_machine`

Stop running work on the Machine. Existing auto_destroy configuration still applies. Requires explicit fly:machines:write authorization.

##### `restart_machine`

Restart the Machine and interrupt its running work. Requires explicit fly:machines:write authorization.

##### `suspend_machine`

Suspend running work on the Machine; this interrupts service until resumed. Requires explicit fly:machines:write authorization.

##### `signal_machine`

Signal Machine. Requires explicit fly:machines:write authorization.

##### `cordon_machine`

Remove this Machine from proxy routing; existing application work can continue. Requires explicit fly:machines:write authorization.

##### `uncordon_machine`

Allow proxy routing to this Machine again. Requires explicit fly:machines:write authorization.

##### `list_machine_events`

List Events. Requires explicit fly:machines:read authorization.

##### `list_machine_versions`

Read historical Machine configurations under explicit authorization. History can contain sensitive environment, file and metadata values. Requires explicit fly:machines:sensitive:read authorization.

##### `list_machine_processes`

Read process details, which can include sensitive command arguments, under explicit authorization. Requires explicit fly:machines:sensitive:read authorization.

##### `wait_for_machine_state`

Wait for State. Requires explicit fly:machines:read authorization.

##### `get_machine_lease`

Read the active lease under an explicit management grant. Lease nonces are sensitive concurrency credentials. Requires explicit fly:machines:write authorization.

##### `get_machine_metadata`

Read arbitrary Machine metadata under explicit authorization; values can be sensitive. Requires explicit fly:machines:sensitive:read authorization.

##### `get_machine_metadata_key`

Read one arbitrary Machine metadata value under explicit authorization. Requires explicit fly:machines:sensitive:read authorization.

##### `exec_machine_command`

Execute an explicit argv array on the Machine, without an implicit shell. Can read or change application data. Command output may contain sensitive values. Requires explicit fly:machines:exec authorization.

##### `create_machine_lease`

Acquire a temporary Machine lease, or renew it with the existing lease_nonce. Keep the returned nonce private; use it for subsequent mutations and release. Requires explicit fly:machines:write authorization.

##### `release_machine_lease`

Release the Machine lease using its exact lease_nonce. Requires explicit fly:machines:write authorization.

##### `get_machine_memory`

Get Machine Memory. Requires explicit fly:machines:write authorization.

##### `set_machine_memory_limit`

Set Machine Memory Limit. Requires explicit fly:machines:write authorization.

##### `reclaim_machine_memory`

Reclaim Machine Memory. Requires explicit fly:machines:write authorization.

##### `update_machine_metadata`

Set or remove metadata keys, without replacing other keys. Null or empty values remove keys. Requires machine_version; stale versions fail without updating. Requires explicit fly:machines:write authorization.

##### `set_machine_metadata_key`

Upsert Metadata Key. Requires explicit fly:machines:write authorization.

##### `delete_machine_metadata_key`

Delete Metadata. Requires explicit fly:machines:write authorization.

#### Volumes (8 tools)

##### `list_volumes`

List volumes, hiding deletion-state volumes by default. Set include_destroyed=true to include them. With summary=true, byte and block statistics are unavailable and omitted. Requires explicit fly:volumes:read authorization.

##### `create_volume`

Create a new billable persistent volume. Restoring or forking another volume is not supported by this tool; those operations require separate source-resource authorization. Requires explicit fly:volumes:write authorization.

##### `get_volume`

Get Volume. Requires explicit fly:volumes:read authorization.

##### `update_volume`

Update Volume. Requires explicit fly:volumes:write authorization.

##### `delete_volume`

Permanently destroy a persistent volume and its data. Detach it from Machines before deletion. Requires explicit fly:volumes:delete authorization.

##### `extend_volume`

Increase persistent volume capacity and associated charges; volumes cannot be shrunk. Requires explicit fly:volumes:write authorization.

##### `list_volume_snapshots`

List Snapshots. Requires explicit fly:volumes:read authorization.

##### `create_volume_snapshot`

Schedule a volume snapshot. The volume must be attached and ready. Creation is asynchronous and may not return a snapshot ID; use list_volume_snapshots afterward to find the snapshot ID and completion status. Requires explicit fly:volumes:write authorization.

#### App secrets (5 tools)

##### `list_app_secrets`

List secret names, digests and timestamps. Secret values are never returned. Requires explicit fly:secrets:read authorization.

##### `get_app_secret`

Read one secret's name, digest and timestamps. Its value is never returned. Requires explicit fly:secrets:read authorization.

##### `update_app_secrets`

Set or remove several secrets. Null values remove secrets and additionally require fly:secrets:delete consent. The upstream bulk API requires create, write and delete action bits even for sets; secret values are never echoed. Requires explicit fly:secrets:write authorization.

##### `set_app_secret`

Set a secret value. The result contains metadata only; secret values are not echoed. Requires explicit fly:secrets:write authorization.

##### `delete_app_secret`

Delete an app secret. Deletion is idempotent: an absent name can still succeed and advance the secrets version. Requires explicit fly:secrets:delete authorization.

#### IP addresses (1 tools)

##### `list_app_ips`

List IP assignments for app. Requires explicit fly:network:read authorization.

#### TLS certificates (2 tools)

##### `list_app_certificates`

List certificates for app. Requires explicit fly:certificates:read authorization.

##### `get_app_certificate`

Get certificate details. Requires explicit fly:certificates:read authorization.

### Sprites

#### Discovery and lifecycle (6 tools)

##### `list_sprites`

List Sprites visible to this connection. The grant's name prefix and optional label filter access; this is not necessarily every Sprite in the organization, nor limited to Sprites created by this client. Call get_fly_context to inspect the restrictions.

##### `create_sprite`

Create a Sprite within this connection's grant restrictions. First call get_fly_context and inspect the Sprites binding restrictions for the required name_prefix and max_sprites_total creation limit.

##### `destroy_sprite`

Destroy a sprite in the authenticated organization.

##### `search_sprite_mentions`

Find up to 20 authorized Sprites by name prefix for composer mentions.

##### `open_sprite_inspector`

Open a read-only Sprite Inspector showing environments, services, checkpoints and recent service logs. Opening only lists metadata; runtime reads are explicit and may wake a Sprite.

##### `get_sprite_info`

Read authorized Sprite metadata without waking it. Pass sprite_id from a mention or Inspector selection to reject deleted and recreated environments.

#### Commands and sessions (3 tools)

##### `exec_list`

List active exec sessions.

##### `exec`

Execute a command via simple HTTP POST (non-TTY only). Simpler alternative for exec for environments that can't handle websockets.

##### `exec_kill`

Kill an exec session by session ID. Returns streaming NDJSON with kill progress.

#### Files and directories (6 tools)

##### `file_read`

Read file contents from the sprite filesystem. Returns raw file bytes.

##### `file_write`

Write up to 16 MiB of file contents to the sprite filesystem. Request body contains raw file bytes.

##### `file_list`

List directory contents.

##### `file_delete`

Delete a file or directory.

##### `file_rename`

Rename or move a file or directory.

##### `file_copy`

Copy a file or directory.

#### Services and logs (6 tools)

##### `service_list`

List all configured services and their current state.

##### `service_get`

Get details of a specific service.

##### `service_create`

Create or update a service definition.

##### `service_start`

Start a service. Returns streaming NDJSON with stdout/stderr.

##### `service_stop`

Stop a running service. Returns streaming NDJSON with service stop progress.

##### `service_logs`

Stream logs for a service.

#### Checkpoints (4 tools)

##### `checkpoint_create`

Create a new checkpoint of the current sprite state. Returns streaming NDJSON progress.

##### `checkpoint_list`

List all checkpoints.

##### `checkpoint_get`

Get details of a specific checkpoint.

##### `checkpoint_restore`

Restore to a specific checkpoint. Returns streaming NDJSON progress.

#### Network policies (2 tools)

##### `policy_network_get`

Get the current network policy configuration.

##### `policy_network_update`

Update the network policy configuration.