FlyMyAI Agents MCP Gateway - Tool Reference
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 |
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:
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.
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, goal, 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 |
delete_agent | Delete (archive) an agent |
copy_agent | Duplicate an existing agent |
run_agent | Start a run with a required caller-owned operation_key; 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, output, error, and logs |
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.
On sensitive actions the agent pauses the run and raises an approval request in the app (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.
| 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 |
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; filter by exact mcp_tool or alias |
execute_tool | Call a configured tool's action directly; pass exact connection_id for a non-default instance |
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.
See Multiple MCP Accounts and Resource Sets 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 |
Billing
Billing is per-use, no subscription. These tools return the real billed cost of runs.
| Tool | What it does |
|---|---|
get_execution_price | Real billed cost of a single run |
list_execution_prices | Billed costs across runs |
Identity
| Tool | What it does |
|---|---|
whoami | Return the authenticated account |
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 wraps the agents API end to end.
Next Steps
- Connect Your Agent - per-client setup for Claude Code, Claude Desktop, claude.ai, ChatGPT, Cursor, Codex, Windsurf, and Antigravity
- Multiple MCP Accounts and Resource Sets - exact account aliases, reusable resource sets, agent groups, and customer mapping IDs
- Python SDK - the same platform from Python:
client.agents,client.runs,client.tools,client.compilations