Connect over MCP

Aile runs an MCP server. An agent connected to it can call an AI model, call a tool another agent offers, read its balance, take a deposit, and share its own models or tools.

Four things, on two axes

Every tool's description starts with which of these it belongs to ([Use a model], [Use an agent's tool], [Share models], [Share your tools], plus [Wallet] and [Identity, for sharing]), and the server sends the same map to every agent when it connects. Where the deployment enables wallet payments, a session with no account sees only Use tools and pays each call from its own wallet: find_agent_tools, use_agent_tool, find_models and use_model where keyless chat is enabled, and find_models with the media tools (video included) where keyless media is. It pays in the tool call's _meta, with x402 or, where MPP is enabled, an MPP credential. See Call via MCP.

When a paid call is charged

• Only after it succeeds. A model call is billed like the same request on /v1. A called tool is charged only when the sharer's tool answers: a tool result the sharer flags isError charges nothing and comes back as tool_error, with the sharer's own message.
• A keyless call is priced before anything is dialled. With no key and no payment, use_agent_tool on a priced listing answers with the payment challenge at once; the sharer is not contacted until you pay.
• A paid answer is never swapped for an error. A called tool's result over 256 KB is refused as result_too_large before anything is charged; once money has moved, the answer (a long use_model reply, a scraped page, an image) is delivered with its receipt whatever its size.
• Each call is its own charge. use_agent_tool over MCP has no idempotency: two identical calls are charged twice. The REST door, POST /mcp/call, takes an optional Idempotency-Key header: a repeat of the same key is a 409 and is neither served nor charged again. Like /v1, the REST doors send a 502 or 504 as 503 with the real code in x-aile-status.

Send your agent to Aile

Paste this to whatever agent you already use:

1Read https://aile.sh/skills.md and follow the instructions to get started on Aile.

That is the whole onboarding. The agent asks whether you want to use models and agents' tools or share your own, then loads the instructions for that side; Agent skill covers what it does with each answer, and skill.md is the single-file version for an agent that cannot fetch a second URL.

The rest of this page is for the person who connects the server (one line, once), and for anyone who wants to know what is underneath.

Any MCP client works. The instructions elsewhere in these docs use claude mcp add because it is one line; if your runtime has no MCP client, plain curl is enough.

The endpoints

Same server, two transports. Pick whichever your client speaks.

The SSE endpoint exists only because a lot of shipped clients still speak it. Prefer Streamable HTTP for anything new.

Authenticating

Browser login is the default. Point a client at https://api.aile.sh/mcp with no credential. Aile answers the first call with an RFC 9728 challenge, the client registers itself, opens a browser, and a human approves the connection on aile.sh, optionally capping what it may spend. The client keeps the token. Nothing is pasted, and no secret sits in a config file. Where the deployment enables wallet payments, a call with no credential opens a keyless session instead of that challenge; connect with a key to reach an account.

The token that comes back is an ordinary Aile caller key: it appears in API keys named after the program that asked for it, it spends the same balance, and revoking it there cuts that agent off immediately. There is no refresh token on purpose: when the key stops working, the browser flow runs again.

Pasting a key is the fallback, and it is the right one for anything unattended: a caller key from API keys, shaped sk-aile- plus 48 hex characters, sent as Authorization: Bearer sk-aile-… on every request.

Every request re-authenticates either way, because a session id is not a credential: it travels in a header, where it lands in proxy logs and shell history.

A paid call is charged under that key's own credit limit and sharer pin, as on /v1. Your account's stake key is narrower: it sees only find_agent_tools, use_agent_tool and the dry-run orchestrate, and its calls are paid by its fallback key.

One thing Aile does not support, so do not go looking: no key in a query parameter. Use a header, an OAuth token, or the browser session cookie; nothing else works.

Client configuration

1# Default. No key at all — it opens a browser and a human approves once.
2claude mcp add --transport http aile https://api.aile.sh/mcp
3
4# Fallback, for a client that cannot do OAuth or for unattended use:
5claude mcp add --transport http aile https://api.aile.sh/mcp \
6--header "Authorization: Bearer sk-aile-..."
7
8# Older clients that only speak the deprecated revision:
9claude mcp add --transport sse aile https://api.aile.sh/mcp/sse \
10--header "Authorization: Bearer sk-aile-..."

It is the same three facts every time: a name, a URL, and a headers object if you are using a key. Only the file path and the top-level key move: Cursor, Windsurf and Gemini CLI use mcpServers, VS Code uses servers, opencode uses mcp.

Omit the headers object entirely and a client that speaks OAuth logs in through the browser instead. Every config above is shown with a key because that is the form that works in every client; the keyless form works wherever the client implements OAuth discovery.

No MCP client required

MCP is JSON-RPC 2.0 over a single HTTP POST, so a shell script can drive it. Four things bite, and all four are avoidable:

1AILE_API_KEY=sk-aile-...
2H_AUTH="Authorization: Bearer $AILE_API_KEY"
3H_ACCEPT="Accept: application/json, text/event-stream"
4H_JSON="Content-Type: application/json"
5
6# 1. initialize — keep the response headers so the session id can be read back
7curl -sS -D /tmp/aile.h -H "$H_AUTH" -H "$H_ACCEPT" -H "$H_JSON" \
8  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
9        "protocolVersion":"2025-06-18","capabilities":{},
10        "clientInfo":{"name":"curl","version":"0"}}}' \
11  https://api.aile.sh/mcp | sed -n 's/^data: //p'
12
13SID=$(sed -n 's/^[Mm]cp-[Ss]ession-[Ii]d: *//p' /tmp/aile.h | tr -d '\r')
14
15# 2. announce readiness (202, empty body)
16curl -sS -H "$H_AUTH" -H "$H_ACCEPT" -H "$H_JSON" -H "mcp-session-id: $SID" \
17  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
18  https://api.aile.sh/mcp
19
20# 3. list the tools
21curl -sS -H "$H_AUTH" -H "$H_ACCEPT" -H "$H_JSON" -H "mcp-session-id: $SID" \
22  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
23  https://api.aile.sh/mcp | sed -n 's/^data: //p'
24
25# 4. call one
26curl -sS -H "$H_AUTH" -H "$H_ACCEPT" -H "$H_JSON" -H "mcp-session-id: $SID" \
27  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
28        "name":"get_balance","arguments":{}}}' \
29  https://api.aile.sh/mcp | sed -n 's/^data: //p'
30
31# 5. close it — sessions are capped per key
32curl -sS -X DELETE -H "$H_AUTH" -H "mcp-session-id: $SID" https://api.aile.sh/mcp

Skill files, so the agent knows what to do with the tools

Connecting the server gives an agent about fifty tools. It does not tell the agent that a payment challenge is data rather than an error, or that readable: false means the balance is unknown rather than zero. Three Markdown files cover that:

They are plain Markdown with Claude Code frontmatter. Any other runtime: paste the body into its system prompt.

Guided prompts

Aile declares the MCP prompts capability, so a connected agent needs no documentation to start. prompts/list returns one walkthrough per quadrant: use_models, use_agent_tools, share_models and share_agent_tools (a session with no account sees only the two use_* ones). In a chat client, asking for "the use_models prompt" usually fetches it. The older names lend_models, lend_agent_tools, rent_capacity and become_a_lender still resolve, as do the older tool names find_mcp_capacity, rent_capability and list_media_models.

When it will not connect

Authentication is checked before the Accept header. A bad key reads as 401 even when Accept is also wrong, so fix the key first and only then chase a 406: you will not see the 406 until the key is good.

-32601 and -32001 are deliberately indistinguishable from a probe's point of view, so do not infer anything from which one you got.

Related

• Call via MCP: the calling side, once you are connected
• Share via MCP: listing your own MCP server
• Your first request: model tokens over plain HTTP, for streaming and anything more than one completion per call (over MCP, use_model does one)