# FlyMyAI Agents MCP Gateway - Tool Reference

> FlyMyAI Agents MCP gateway tool reference at mcp-agents.flymy.ai/mcp, grouped by agents, freeze, models, tools, MCP servers, MCP resource sets, skills, files, artifacts, and billing.

The FlyMyAI Agents MCP gateway exposes the whole FlyMy.AI platform - agents, frozen compilations, media models, the connector catalog, external MCP servers, skills, files, and billing - as a single MCP server your AI client can call.

| | |
|---|---|
| **Endpoint** | `https://mcp-agents.flymy.ai/mcp` |
| **Transport** | Streamable HTTP |
| **Auth (GUI clients)** | OAuth sign-in on connect (Claude Desktop, claude.ai, ChatGPT) |
| **Auth (CLI / config clients)** | Header `X-API-Key: YOUR_KEY` - get a key at [app.flymy.ai/profile](https://app.flymy.ai/profile) |

First make one bounded read-only call such as MCP `tools/list` or `whoami`. If
the FlyMyAI server or tools are absent, do not claim that it is connected and
do not guess lifecycle tool names. Connect the exact intended environment.
Released production can be selected explicitly as follows; a release candidate
must supply its own `FLYMYAI_MCP_URL` and must not fall back to this value:

```bash
export FLYMYAI_MCP_URL=https://mcp-agents.flymy.ai/mcp
: "${FLYMYAI_MCP_URL:?Set the exact MCP endpoint}"
claude mcp add --transport http flymyai "$FLYMYAI_MCP_URL" --header "X-API-Key: YOUR_KEY"
```

GUI clients can use OAuth sign-in. Keep CLI keys in a secret manager rather
than pasting them into chat. If MCP remains unavailable, use REST only after
the caller supplies an authenticated exact Agents API root.

For Cursor, Codex, Windsurf, Antigravity, and GUI clients, see [Connect Your Agent](https://docs.flymy.ai/agents/guides/connect-your-agent.md).

> **Note: The tool list is dynamic**
>
> The list is discovered at runtime via `tools/list` and may grow - treat the
> tables below as a snapshot of the stable core, and treat `tools/list` as the
> source of truth. Descriptions of each tool's exact parameters come from the
> tool schemas your client receives on connect.

Release automation can discover the exact declarative owner and trusted
bound-customer schema at `/agents-mcp-tool-schema.json` beside the public
`/agent-guide-release.json`. Runtime `tools/list` and that exported schema use
the same projector. The owner surface does not administer product customers or
accept a model-supplied `external_user_id`; publish and customer lifecycle stay
on typed REST and SDK operations.

## Agents

Create, run, and manage cloud agents. Runs execute asynchronously in the FlyMy.AI cloud - start a run, then poll it with `get_run`.

| Tool | What it does |
|---|---|
| `create_agent` | Create an agent with a name, `user_prompt` or `user_prompt_source` for instructions from a file, optional schemas, tools, custom MCP servers, MCP resource-set IDs, and explicit `mcp_access_mode` when needed |
| `get_agent` | Fetch one agent with full details |
| `list_agents` | List your agents; `page_size` is 1-100 and `next_cursor` continues the result set |
| `update_agent` | Patch one agent; `agent_id` is required and other accepted fields are optional. `preview` (at most 280 characters) is what people read before they copy it; your text stays through later freezes, and `""` lets FlyMyAI write it again |
| `delete_agent` | Delete (archive) an agent |
| `copy_agent` | Duplicate an existing agent |
| `run_agent` | Start a run with its first `message` and a required caller-owned `operation_key`; answers at once with a short receipt (run `id`, `status`, `run_seq`, `subagent_limits`) while the agent executes asynchronously in the cloud |
| `append_message` | Add a follow-up message to a run and continue the agent loop |
| `get_run` | Get a run's status, new steps, and, on the final page, bounded `result` and `error` previews with `size_bytes`, `sha256`, and a `ref` |
| `read_run_result` | Read the whole result or error of a finished run by the `ref` from `get_run`, up to 64 KiB per call; continue from `next_offset` until `complete` |
| `cancel_run` | Cancel a run that is still in progress |
| `favorite_run` | Mark a run as a favorite |
| `set_agent_public` | Toggle an agent's public visibility |
| `set_effort` | Adjust the agent's effort setting |
| `suggest_schema` | Suggest an input/output schema for an agent |

Discover the current `update_agent` request schema from MCP `tools/list`
before changing attachment fields. In the current contract, an omitted field
is unchanged and an explicit empty relation array clears it. For example,
moving the same logical agent from a legacy connection attachment to resource
slots requires both `available_tools:[]` and the intended
`mcp_resource_set_ids`, plus `mcp_access_mode:"scoped"`, followed by
`get_agent` to verify the replacement. The direct one-account projection uses
`mcp_access_mode:"legacy"`. The simple and advanced paths are two modes of the
same agent, not different agent types.
Direct attachments and set grants otherwise form a union.

`list_agents` is cursor-paginated. Continue with the returned `next_cursor`
until it is absent instead of assuming the first page is complete.

A finished run's result or error can be longer than the 4 KiB preview on the
final `get_run` page. Pass that page's `result.ref` (or `error.ref`) with the
same `execution_id` to `read_run_result`, then keep reading from `next_offset`
until `complete` is true. The SHA-256 of the joined bytes equals the `sha256`
from `get_run`. If the run changes after a follow-up message, the old ref is
stale: call `get_run` again for a fresh one.

> **Note: Human-in-the-loop**
>
> On sensitive actions the agent pauses the run and raises an approval request in the app ([app.flymy.ai](https://app.flymy.ai)); the run continues after the owner approves.

## Freeze and Compilations

A frozen compilation replays a fixed instruction - deterministic, cheaper, faster. A model update never changes a frozen endpoint; you cut a new version when you choose. "Freeze" and "compile" are the same operation - see [Freeze & Re-run](https://docs.flymy.ai/agents/concepts/runs.md#freeze--re-run).

| Tool | What it does |
|---|---|
| `freeze_agent` | Freeze a successful run into a fixed instruction (compilation) |
| `run_frozen` | Run a frozen compilation with a required caller-owned `operation_key` and optional fresh variables; answers with the same short receipt as `run_agent` |
| `get_compilation` | Fetch one compilation with its status and instruction |
| `list_compilations` | List your compilations |
| `update_compilation` | Update a compilation's settings |
| `schedule_agent` | Set a 5-field cron schedule (plus optional IANA timezone) on a compilation; the schedule fires per compilation |

`run_agent` and `run_frozen` require a nonblank printable ASCII `operation_key`
of 1-255 characters with no leading or trailing spaces. The gateway forwards
it as `Idempotency-Key` and never generates a
fallback. Reserve it before dispatch, reuse it only for an identical request,
and use a new key for a new logical run. Direct REST task, compilation, and
deployment run submissions require the same rule in the `Idempotency-Key`
header.

## Models

Direct access to the FlyMy.AI model catalog - image, video, and other generative models. The catalog changes over time, so discover models at call time instead of hardcoding names.

| Tool | What it does |
|---|---|
| `recommend_model` | Pick the best model for a task; the authoritative list of available models |
| `get_model_schema` | Return the input parameter schema for a `model_id` |
| `run_model` | Run a chosen `model_id` with parameters from its schema; billed to your key |
| `list_media_models` | List available media generation models |
| `flymyai_models` | List models available on FlyMy.AI |
| `get_pricing` | Return the real billed cost per run |

## Tools and Connectors

The platform connector catalog - search it, add a connector, configure it, and call its actions directly without running a full agent.

| Tool | What it does |
|---|---|
| `search_tools` | Search the connector catalog by keyword |
| `list_configured_tools` | List one secret-free bounded cursor page (25 rows by default); filter by exact `mcp_tool` or `alias`. Unfiltered rows are compact; `mcp_tool` or `view=full` adds setup steps, status reasons, and `connect_url` |
| `execute_tool` | Call a configured tool's action directly; pass exact `connection_id` for a non-default instance. `outcome=rejected` carries the reason nothing was done; `outcome=unknown` must be reconciled, never repeated |
| `add_tool` | Create one exact catalog connection; pass a unique `alias` to connect the same toolkit again |
| `update_tool` | Update a tool's settings |
| `delete_tool` | Remove a tool from your workspace |
| `set_tool_config` | Set a tool's configuration values |
| `provide_tool_config` | Provide values for a tool's next configuration step (for example an API key) |

`add_tool` returns the exact connection when it is configured. For an
unconfigured connection, the current gateway returns guidance text containing
the hosted `https://app.flymy.ai/mcp-configs#<slug>?connection_id=<public UUID>`
link plus its alias, public UUID, and numeric compatibility ID. A slug-only
link is used only before an exact row exists. It does not define a `setup_url`
field. After setup, match that exact row in `list_configured_tools` and inspect
`is_configured`, `next_configuration_step`, `connection_status`,
`connection_status_reason`, `connection_status_checked_at`,
`connection_status_valid_until`, `connection_status_reason_code`, and
`connect_url`. The known readiness states are `connected`, `setup_required`,
`reconnect_required`, `verification_pending`, and `temporarily_unavailable`.
Pass `next_cursor` back unchanged while it is non-null. Omitting
`execute_tool.connection_id` is supported only while one eligible connection
is unambiguous; the gateway does not choose an alias by list position.

## External MCP Servers

Bring your own MCP servers: register any external server, connect it, and call its tools through the gateway.

| Tool | What it does |
|---|---|
| `add_mcp_server` | Register an external MCP server |
| `list_mcp_servers` | List your registered external MCP servers |
| `update_mcp_server` | Update a registered server's settings |
| `delete_mcp_server` | Remove a registered server |
| `connect_mcp_server` | Connect to a registered server |
| `disconnect_mcp_server` | Disconnect from a server |
| `call_mcp_server` | Call a tool on a connected external MCP server |

## MCP Resource Sets and Agent Groups

The first personal connection can be attached directly to one agent and does
not require a resource set. Use the tools in this section when a second account,
reusable sharing, or an external-customer mapping creates a real need for the
advanced model.

An MCP resource set is a named collection containing exact connection or custom
server public IDs. It can be granted directly to an agent through
`mcp_resource_set_ids` or shared with several agents through one flat agent
group. Aliases are labels only; runtime selection uses stable public UUIDs.
Member identity is `(resource_type, resource_id, slot)`, so one exact resource
may fill several different slots with an independent action ceiling in each.
The same tuple cannot appear twice.

For a member, omitting `allowed_actions` or sending `allowed_actions:[]` means
there is no additional set-level ceiling - it does not deny every action. Send
the exact discovered read actions when the workflow needs least authority.

| Tool | What it does |
|---|---|
| `list_mcp_resource_sets` | List one bounded summary page with `member_count` and no nested members |
| `get_mcp_resource_set` | Read one set, its exact members, and current revision |
| `list_mcp_resource_set_members` | List one bounded cursor page of exact members for a set |
| `create_mcp_resource_set` | Create an owner resource set (`management_mode=flymyai`, no `principal_id`) or a customer-managed named mapping (`management_mode=customer`, exact `principal_id`); requires a caller-owned `operation_key` |
| `update_mcp_resource_set` | Update set metadata or disable a set with the current `expected_revision` |
| `replace_mcp_resource_set_members` | Atomically replace exact members with `expected_revision` conflict protection |
| `delete_mcp_resource_set` | Delete set membership and grants without deleting connector accounts |
| `list_agent_groups` | List one bounded cursor page of flat owner-scoped agent groups |
| `get_agent_group` | Read one group and its exact assignments |
| `create_agent_group` | Create a group with agent and resource-set public IDs; requires a caller-owned `operation_key` |
| `update_agent_group` | Replace supplied assignment lists or update group metadata |
| `delete_agent_group` | Remove a group without deleting its agents, sets, or connections |

For either durable create, persist `operation_key` with the exact canonical
input before dispatch. Retry an uncertain response only with that same key and
identical input. Reusing the key with changed input returns 409; rotating the
key can create a second set or group.

`list_mcp_resource_sets`, `list_mcp_resource_set_members`, and
`list_agent_groups` return exactly
`{next_cursor, previous_cursor, results}`. `page_size` is 1-100, `cursor` is an
opaque, nonblank printable value of at most 1024 Unicode code points. Optional
`query` is at most 256 printable characters on resource-set and agent-group
lists; the member list accepts only `resource_set_id`, `page_size`, and
`cursor`. Pass `next_cursor` back unchanged. Do not use offsets or assume a
first page is complete. Resource-set list rows contain
`member_count`; use detail for one bounded full representation or the members
tool for a large membership collection.

## Trusted customer-bound deployment tools

These tools are not added to the owner surface. They appear only when a
separate gateway process starts with `FLYMYAI_MCP_MODE=customer` and trusted
server configuration binds one immutable deployment/customer binding per
gateway process:

| Tool | What it does |
|---|---|
| `run_bound_deployment` | Run the pre-bound deployment with only `variables` and required `operation_key`; the gateway forwards a deterministic namespaced key derived from the bound deployment, `external_user_id`, and your `operation_key`, so reuse of the same value still replays exactly one run |
| `get_bound_deployment_run` | Poll only a handle issued by that pre-bound surface |

The trusted process supplies deployment ID, `external_user_id`, and optional
resource-set or exact-connection mapping. Those fields are absent from the tool
schemas and are never model-call arguments. Another customer requires a
separately trusted binding. See
[Per-customer MCP Access](https://docs.flymy.ai/agents/guides/embedded-mcp.md#optional-customer-bound-mcp-runtime).

See [Multiple MCP Accounts and Resource Sets](https://docs.flymy.ai/agents/guides/mcp-resource-sets.md) for
the complete alias, set, grant, runtime selector, freeze, and customer mapping
flow.

## Skills

Reusable skills you can attach to agents.

| Tool | What it does |
|---|---|
| `create_skill` | Create a skill |
| `get_skill` | Fetch one skill |
| `list_skills` | List your skills |
| `attach_skill` | Attach a skill to an agent |
| `detach_skill` | Detach a skill from an agent |

## Files

Files attached to an agent - inputs it should work with and outputs it produced.

| Tool | What it does |
|---|---|
| `attach_files` | Attach files to an agent |
| `list_agent_files` | List files attached to an agent |
| `files_tree` | Show an agent's file tree |
| `download_file` | Download a file |
| `delete_agent_file` | Delete a file from an agent |

## Artifacts

Frontend artifacts - pages, presentations and mini games with versions, shared by link or with
people by name, cloned into your own copy. Available on every owner sign-in (a personal API key or
your assistant's OAuth sign-in); see [Frontend Artifacts](https://docs.flymy.ai/agents/guides/artifacts.md).

When a person pastes `<link> add these things to the artifact: <change>`, open the link with
`get_artifact` and follow its `next`: the owner or an editor publishes the change as a new version
next to the live one (`publish: false`) and makes it live only when the person asks to update the
current version; anyone else clones it and changes the copy.

| Tool | What it does |
|---|---|
| `list_artifacts` | List your artifacts, or (`scope: "shared"`) the ones shared with you |
| `list_artifact_types` | The standard types a new artifact can start from: presentation, game, landing, report, dashboard, gallery |
| `get_artifact` | Open one by id or its page URL (`/artifacts/<id>`), or by its share link; `next` says how to change it, `version` opens a saved version |
| `create_artifact` | Create an artifact from its files or a standard `type`; version 1 goes live, private |
| `publish_artifact_version` | Publish a version on top of the latest or the live one (owner or editor); `publish: false` keeps the live version |
| `read_artifact_files` | Read a version's file list or one text file |
| `update_artifact` | Rename, describe or choose the live version |
| `share_artifact` | Private, link or public, with or without sources; reset the link |
| `clone_artifact` | Make your own copy of an artifact you may open |
| `get_artifact_lineage` | Where it came from and its clones |
| `list_artifact_members` | Who it is shared with by name, and who has not accepted yet |
| `add_artifact_member` | Invite a person to view or edit; they accept first |
| `remove_artifact_member` | Stop sharing with someone by their member id, or leave |
| `list_artifact_invitations` | Artifacts shared with you that wait for your answer |
| `accept_artifact_invitation` | Accept one: the artifact is shared with you from now on |
| `decline_artifact_invitation` | Decline one: nothing is shared |
| `delete_artifact` | Delete it; its link and open pages stop |

## Projects

A project is what you build and run as one unit: an app applied from one `flymy.yaml`, a page
published on its own, a fleet (a lead agent and the agents it starts) or a frontend artifact. A
project is its config: creating, stopping and starting it are a plan and an apply, and each leaves
a release. See [Projects](https://docs.flymy.ai/agents/guides/projects.md).

| Tool | What it does |
|---|---|
| `projects_list` | Your apps and pages, then your fleets, with status, money and errors |
| `projects_get` | One project: its pages, agents, servers, storages, money, errors and diagram |
| `projects_errors` | A page of its errors journal, newest first, last 30 days |
| `projects_templates` | The gallery a new project can start from |
| `projects_plan` | What a new project would make and cost; creates nothing, returns `plan_token` |
| `projects_create` | Create exactly the plan the user confirmed |
| `projects_agent` | The agent in charge of an app or a page, created on first use |
| `projects_stop` | Stop an app or a page: its servers stop and the rest of their holds is refunded |
| `projects_start` | The plan of the start and its price, then the confirmed start |

A fleet (`fleet:<lead agent id>`) and an artifact (`artifact:<artifact id>`) are read with
`projects_get` and `projects_errors`; they are not stopped or started, and an artifact changes
through the artifact tools.

## Apps and their storage

An app is one `flymy.yaml`: its pages and the calls they may make, its agents, the models and tools
they use, rented servers, one or more storages and its budgets.

| Tool | What it does |
|---|---|
| `apps_catalog` | What this platform runs of the `flymy.yaml` language, read before writing one |
| `apps_plan` | What applying a template or a change would create and cost, without spending |
| `apps_apply` | Apply exactly the plan the user confirmed |
| `apps_list` | The apps you applied, each with its latest release |
| `apps_status` | One release of an app |
| `apps_files` | The applied template's files, to change them |
| `apps_remove` | Remove one on-demand instance of an applied app |
| `apps_storage_list` | An app's storages, or one page of a storage's files by folder |
| `apps_storage_read` | Read one file of a storage by path |
| `apps_storage_write` | Write one file at a path; `if_match` guards the version you read |
| `apps_storage_delete` | Delete one file by path |

## Sites

| Tool | What it does |
|---|---|
| `publish_site` | Publish a static page - HTML, JS, CSS and assets - as a FlyMyAI site |
| `list_sites` | Your sites, newest first |
| `get_site` | One site |
| `share_site` | Turn its public link on or off |
| `invite_to_site` | Give one person access by email |
| `revoke_site_access` | Remove one person's access |
| `remix_site` | Copy a site into your account as your own |
| `get_site_usage` | What powers your sites and what they cost |

## Billing

Billing is per-use, no subscription. These tools return what runs used and cost: every tool call and model answer with its price in USD. A row marked `settled` is charged; before that (about 10 minutes) it shows the estimate the charge will use, and `billing_settled` says the run's total is final.

| Tool | What it does |
|---|---|
| `get_execution_price` | What one run used and costs: tool calls, model answers (fresh, cached and reasoning tokens), `run_model` generations, totals |
| `list_execution_prices` | The same for your newest runs (100, up to 200 with `limit`), or for the runs named in `ids` |

## Identity

| Tool | What it does |
|---|---|
| `whoami` | Return the authenticated account |

> **Tip: Prefer REST or an SDK?**
>
> Everything the gateway does is also available programmatically. Released
> production uses `FLYMYAI_AGENTS_API_ROOT=https://backend.flymy.ai/api/v1/agents`;
> a candidate must supply its own root and must not fall back to production. The
> models API is at `https://api.flymy.ai/api/v1/...`; both use `X-API-KEY`. The
> [Python SDK](https://docs.flymy.ai/agents/sdk/python.md) wraps the agents API end to end.

## Next Steps

- **[Connect Your Agent](https://docs.flymy.ai/agents/guides/connect-your-agent.md)** - per-client setup for Claude Code, Claude Desktop, claude.ai, ChatGPT, Cursor, Codex, Windsurf, and Antigravity
- **[Multiple MCP Accounts and Resource Sets](https://docs.flymy.ai/agents/guides/mcp-resource-sets.md)** - exact account aliases, reusable resource sets, agent groups, and customer mapping IDs
- **[Python SDK](https://docs.flymy.ai/agents/sdk/python.md)** - the same platform from Python: `client.agents`, `client.runs`, `client.tools`, `client.compilations`, `client.artifacts`

## Typed decisions

For fast classification, routing, triage, fixed-enum extraction and yes/no gates, use [TypeSafe Jev 1.13](https://docs.flymy.ai/guides/typesafe-jev). It accepts `state` and typed `questions` through its JSON Decisions endpoint and returns Choice, Noul probability or Score answers. It is not a chat model and does not generate prose, code or media. Both MCP servers expose `make_typed_decision`; agents discover `typesafe_jev.decide`.

## Webhook triggers v1

The versioned `triggers_v1_*` MCP tools and the `client.triggers_v1` SDK resource
(`flymyai` 1.2.0rc15 or later) manage signed webhooks for a Live saved agent
version. See [Webhook Triggers v1](https://docs.flymy.ai/agents/guides/webhook-triggers.md) for signing,
stable write keys, receipt history, limits and pause semantics.