Let your coding agent read the docs, list models, lease a session and read its trace. Two servers, same tools:
a hosted one at https://api.agi.diy/mcp and a local one, agi mcp, that also reaches the wire.
Connect your agent#
Read first, without a key#
claude mcp add --transport http agi https://api.agi.diy/mcp Public mode exposes docs and live model availability. Account tools require a private API key created in the dashboard. Configure it through your client's secret configuration; never commit a real key to a repository. For Claude Code, with AGI_API_KEY privately set in your environment:
claude mcp add --transport http agi-account https://api.agi.diy/mcp --header "Authorization: Bearer $AGI_API_KEY" This command may persist the expanded header in the client's configuration; keep that file private.
Codex (~/.codex/config.toml; replace the placeholder locally):
[mcp_servers.agi]
url = "https://api.agi.diy/mcp"
http_headers = { Authorization = "Bearer YOUR_PRIVATE_KEY" }Cursor (.cursor/mcp.json; keep this out of version control if it contains a key):
{"mcpServers":{"agi":{"url":"https://api.agi.diy/mcp","headers":{"Authorization":"Bearer YOUR_PRIVATE_KEY"}}}}Local (pip install agi-diy && agi login; the server reads ~/.agi/credentials, no key in the config):
claude mcp add agi-local -- agi mcp # one name per server: agi (hosted, docs only) · agi-account (hosted, with a key) · agi-local (this one)
# Cursor / Codex: command "agi", args ["mcp"]Without a key the hosted server exposes the docs tools only (quickstart, search_docs, models) so an agent can
read before you have a key. GET https://api.agi.diy/mcp prints the add line.
Then say to your agent:
Read agi.diy compatibility and prepare a dry run for my control loop. Ask before paid inference, replay or anything that could move hardware.
Tools#
| tool | needs key | what |
|---|---|---|
quickstart | no | Three starting paths: browser simulation, calibrated SO-101, or an existing integration. |
search_docs {q} | no | Grep the docs (QUICKSTART, API, ROLLOUT, TRACE, WIRE, MCP, CONTRACT) for a word or phrase; each hit carries section (nearest heading) and context (the enclosing code block, else ±2 lines). ≤10 hits. |
models | no | Models online right now: free slots, actions per call, fps, camera names — plus units and units_note, which the service writes itself (worker/src/units.ts, one constant behind REST /v1/models, the hosted tool and this row), because two semantics labels are live (agi-* rows so101-normalized-v1, stock-* rows the legacy so101-degrees-gripper-percent-v1) while the data is LeRobot normalized under either. The local server passes that text through unchanged and only adds a pointer of its own against an older Worker, so an agent cannot read two different corrections. |
me | yes | Who the key belongs to and the credits left. |
usage {since?} | yes | Tokens used per model since a date (default 30 days). |
create_session {model, ttl_s?, record?, hf_token?} | yes | Lease one slot (or hf:<org>/<repo> for your own checkpoint — starts warming, poll session until leased); returns the lease (endpoint, deployment, semantics, action_horizon, connect_by) plus commands.lerobot_rollout, commands.agi_rollout, commands.python for it. |
session {id} | yes | One session: state, tokens used, end reason, public (TRACE.md "Public sessions"). |
end_session {id} | yes | End a session now; the slot returns to the pool. |
trace {id, from?} | yes | What the policy saw and answered: observation states and action chunks (no frames). |
replay {id, model?} | yes | Feed a recorded session's observations to a model again as a new, billed session. |
Local only (agi mcp). probe opens the Zenoh wire; rollout_dry_run only prepares configuration:
| tool | what |
|---|---|
probe {model, n?, task?, ttl_s?} | Lease, connect, send n synthetic observations (default 3); returns chunk shape, per-call ms, tokens billed. Installs lerobot on first use. |
rollout_dry_run {model, args?, fake?} | Compose the exact lerobot-rollout command and camera mapping for your flags; fake: true plans the hardware-free robot. Leases nothing. |
Resources: agi://docs/WIRE, agi://docs/QUICKSTART, agi://docs/API, agi://docs/ROLLOUT, agi://docs/TRACE, agi://docs/MCP,
agi://docs/CONTRACT, agi://docs/CONCEPTS — the docs as markdown. CONCEPTS is the vocabulary page both servers point
agents at (https:): token, chunk, "did it work?", normalized units, what a session costs
per minute. It is now readable through resources/read and searchable with search_docs, so an agent gets those
definitions first-hand instead of second-hand (W2-89).
A session leased through create_session bills tokens once a client calls it, like any other. It ends at
connect_by (+60 s) if nothing connects, at end_session, or at its TTL.
Protocol#
Streamable HTTP, JSON-RPC 2.0, stateless: every POST /mcp carries its own Authorization; no session id, no
server-sent stream (GET /mcp with Accept: text/event-stream answers 405; DELETE /mcp answers 204). Protocol
versions 2025-06-18, 2025-03-26, 2024-11-05. Methods: initialize, ping, tools/list, tools/call,
resources/list, resources/read, resources/templates/list, prompts/list; notifications answer 202. Batches
are accepted. Tool errors come back in-band (isError: true, structuredContent.error = the REST error code); a bad
key is 401 at the HTTP layer; a missing key hides the tools that need one.
curl -s https://api.agi.diy/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"models","arguments":{}}}' The local server is the same handler over stdio (one JSON-RPC message per line, as the MCP stdio transport
specifies), implemented in agi/mcp.py with the standard library only.
Cost, privacy and physical safety#
The hosted server manages sessions and records; it does not execute actions on your motors. A local probe performs real paid inference with synthetic inputs (default 3 calls; set n:1 for one). A replay is also new, billed inference. Read-only model/docs/usage/trace tools do not start inference.
Trace data includes private state/task information; frame references may point to camera images. Trace API access lasts 24 hours from session creation; operators with authorized cookies can inspect it. create_session accepts record:false to disable recording, not billing/accounting.
Use a client approval policy for session creation, paid probes and replay. Preparing a rollout is not permission to execute it. Current SO-101 action values are normalized, despite the misleading degrees identifier: verify calibration, transforms, camera views and local limits before physical execution.