Setup
Connect your client
Choose your harness for setup instructions. Each connects to the same Fly MCP server using browser sign-in.
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.
Try your first tool
Once connected, try this read-only prompt. Check the organization in the result before asking your client to make changes.
PromptList the Sprites I can access and show the organization name. Do not create, change, or delete anything.
Sprites
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.
First prompts
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
PromptList the Sprites I can access. Show metadata for the one I select, without waking it or changing anything.
Try a disposable environment
PromptCreate 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
PromptShow 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.
Access
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.
Troubleshooting
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.
Reference
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 context4 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
Apps3 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.
Machines28 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.
Volumes8 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 secrets5 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 addresses1 tool
list_app_ips- List IP assignments for app. Requires explicit fly:network:read authorization.
TLS certificates2 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 lifecycle6 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 sessions3 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 directories6 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 logs6 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.
Checkpoints4 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 policies2 tools
policy_network_get- Get the current network policy configuration.
policy_network_update- Update the network policy configuration.