Antfly MCP#

Antfly Cloud exposes each hosted instance as a remote Model Context Protocol server. Agent clients connect to CloudAF, CloudAF authenticates the caller, and Antfly enforces the resulting instance permissions before listing or running MCP tools.

Endpoint#

Use the Cloud instance MCP endpoint:

https://platform.antfly.io/cloud/v1/<instance_id>/mcp/v1

Replace <instance_id> with the hosted Antfly instance ID.

Do not connect external clients directly to an internal instance /mcp/v1 route. External clients should use the Cloud endpoint so authentication, permission scoping, metering, and routing stay in one place.

Authentication#

Use an instance-scoped Antfly Cloud API key:

Authorization: Bearer antflydb_<key>

CloudAF validates the API key, resolves its instance permissions, strips external credentials, and forwards a short-lived trusted principal to the managed Antfly instance. Antfly uses that principal to decide which MCP tools are visible and which tool calls are allowed.

API keys are shown only once when created or rotated. Do not commit real keys to a repository or share them in prompts, logs, screenshots, or support tickets.

Transport#

Antfly MCP uses streamable HTTP:

POST for MCP JSON-RPC requests
GET for server-sent event streams and reconnects
DELETE to close a streamable HTTP session
Mcp-Session-Id for session continuity
Last-Event-ID for reconnect cursors

The protocol version is 2025-06-18.

Permission Tiers#

Antfly Cloud API keys have three instance permission tiers.

Tier	Tools
Read-only	`list_tables`, `describe_table`, `list_indexes`, `describe_indexes`, `get_document`, `sample_documents`, `query`, `describe_query_request`, `describe_mcp_capabilities`
Read/Write	All read-only tools plus `batch`
Admin	All read/write tools plus `create_table`, `drop_table`, `create_index`, `drop_index`, `backup`, `restore`

Use the narrowest key that fits the client. Retrieval-only agents should use read-only keys. Agents that index or update data need read/write keys. Reserve admin keys for automation that must manage tables, indexes, backups, or restores.

Tool visibility is permission-scoped. If a key does not have access to a tool's required operation, that tool is not listed for the client.

Client Guides#

Microsoft Copilot Support Agent

Smoke Test#

After configuring a client, verify the connection with a small read operation:

List the Antfly MCP tools you can use, then list the available Antfly tables.

A read-only key should not show write or admin tools. A read/write key should show batch but not table or index administration tools. An admin key should show the full tool set.

If the client should read a specific table, ask it to list tables first and then describe or query the exact table name returned by Antfly.

Troubleshooting#

Symptom	Check
The client cannot connect	Confirm the URL uses `/cloud/v1/<instance_id>/mcp/v1` and the instance ID is correct.
Authentication fails	Confirm the header is exactly `Authorization: Bearer antflydb_<key>`.
Tools are missing	Confirm the key tier and any table grants for the key. Tool visibility follows the key's effective permissions.
Browser-based clients fail before sending a request	Confirm the client sends only allowed MCP headers such as `Authorization`, `Content-Type`, `Mcp-Session-Id`, `Mcp-Protocol-Version`, and `Last-Event-ID`.
Reconnects fail	Confirm the client preserves `Mcp-Session-Id` and sends `Last-Event-ID` when reconnecting.