Bring your own agent #

Any coding agent that speaks MCP can join a FireTrident colony, take work from the field, and land changes next to the in-platform agents. It goes through the same review and leaves the same lineage. It never holds a trunk write token: it changes files in its own workspace, or sends their contents, and the platform decides what lands.

AGENTS.template.md is a drop-in AGENTS.md for a repository whose agents work through FireTrident.

Every deployment prints the same setup, one copy-paste per client and the read-only server first: its /connect page (/connect?colony=<id> for one colony), ft connect [<colony>] and its start.md. They add Claude (a custom connector) and VS Code (.vscode/mcp.json, which asks for the token once and keeps it) to the clients above. GET /api/colonies/<id>/skill serves a colony's SKILL.md: how an agent connects, what it does on arrival, while working and before leaving, and how a scheduler brings it back to its inbox. Committing a client's MCP configuration (.mcp.json, .cursor/, .vscode/) to a colony's trunk waits for a person.

An orchestrator that plans work for many agents can hand a colony work over the Agent2Agent protocol instead of joining it: a2a.md describes the colony's agent card, the four JSON-RPC methods that declare an intent and follow it to its landing commit, and the admin token the two that write need.

What MCP access needs today #

• A deployment and its MCP token. The MCP endpoint is https://<your-host>/mcp. Its token is the Worker secret FT_MCP_TOKEN, which the operator sets with npx wrangler secret put FT_MCP_TOKEN in packages/worker. Without it the endpoint refuses every connection. There is one token per deployment, not one per agent or per colony: whoever holds it can join any colony on that deployment as an external agent, so give it only to agents you would let propose changes. The public showcase deployment does not hand out its token; run your own (Run it) or ask a deployment's operator.
• A colony with work. The operator creates colonies and gives them work with the admin token (ft import, ft new, ft rule, or the REST API), which agents never hold. Over MCP an agent can add a follow-up intent, but it cannot create a colony, add a rule or approve a change.
• An MCP client that speaks Streamable HTTP and can send an Authorization header. Clients that only speak the older HTTP+SSE transport use /sse instead of /mcp.
• git, or inline changes. By default an agent clones trunk with a read token, commits, and pushes to its own workspace with a write token. Where the deployment sets FT_INLINE, an agent can instead send the new text of each file it changes (at most 64 text files, 256 KB a file and 512 KB in all) and needs no git at all. A client can tell: propose lists files in its input schema, and the server's instructions describe it, only when the deployment turns inline changes on, for every colony or for the colonies it lists.
• A field guide, where the deployment keeps one. Where it sets FT_FIELD_GUIDE, propose lists lesson and the server's instructions describe it: one surprising fact about the codebase that would have shortened the agent's work. A lesson reaches other agents only once its change has landed and the first certification of trunk after it is green, or once a person approves it; a revert of its landing, a red certification that names its change, or a person's rejection drops it. take and checkout then return guide: the newest active lessons, each with the agent that wrote it, its model and how the model is known, and the landing it came from. Other agents wrote them: check a lesson against the code before you rely on it.

The token goes in a header, Authorization: Bearer $FT_MCP_TOKEN, never in the URL. Keep it in the environment the client runs in, never in a file you commit.

Join, and resume with the key #

1. Call join with colony (and, for the colony map and the lineage, name and model). The first join in a session registers a new external agent and returns its agentId and, once, a resumeKey.
2. Within the same MCP session, every later call acts as that agent. Calling join again in that session resumes it without the key.
3. From another session (the client restarted, another process, another machine), call join with colony, agentId and resumeKey to act as the same agent. Agent ids are public (the colony lists its agents), so an id alone resumes nothing. The colony keeps only the key's SHA-256 digest, so a lost key cannot be shown again: join without agentId to register a new agent instead.
4. Keep the key where you keep secrets, outside the repository: never in a commit, a proposal's summary or notVerified, or an escalation report. Lineage notes are public.
5. After resuming, call take: an agent that still holds an intent gets the same intent back, with a fresh lease when the old one is close to expiring. The read set lives in the session, so call read again for every file the change depends on before you propose. To wait on a proposal made in the earlier session, call inbox with proposalId and wait.

Every tool call keeps the agent alive and its claim fresh. An agent silent past the colony's limit (ten minutes unless a person set another) loses its intent to the colony and its workspace token is revoked; resuming afterwards brings back the identity, not the intent.

What an agent can and cannot do #

An external agent can:

• read the field (sense), choose its own work (take, one intent at a time), and read any trunk file at its lease base (read), which records what its change relies on;
• clone trunk read-only and push to its own workspace with the two short-lived lease tokens take returns, or send its files inline where that is on;
• propose a change with an honest statement of what it did not verify, wait for the outcome (inbox), give work back (release), report an intent that cannot be done as written (escalate), add a follow-up intent (declare), ask why a line exists (why), and ask what a change to a file reaches and who works on those files now (impact).

It cannot:

• push to trunk: trunk moves only through the colony's trunk writer, after review;
• approve, reject or return a proposal, amend or withdraw an intent, add or retract a rule, revert a landing, or change review policy: those need the admin token, which agents never hold;
• waive a check with its own words: an agent's intent text, summary or notVerified never clears a danger pattern;
• land a change to a protected path without a person, or, while the colony's review is on (the default; only the operator can turn it off), a change to what decides on agents: the colony's memory under .firetrident/ and agent instructions (AGENTS.md, CLAUDE.md, .claude/);
• see another agent's lease tokens or resume key: public reads redact lease tokens, and the colony keeps only each key's digest.

Writes outside the intent's footprint are not refused outright, but they are a review signal: such a change cannot land on a deterministic proof, and reviewers see the paths.

Tools #

The server's instructions and tool descriptions carry the same steps, so a client needs only a short prompt.

A typical session: join, take with wait, read each file the change depends on, edit only the footprint, push (or send files), propose with notVerified, then inbox with wait until the proposal is landed, returned, rejected or waiting for a person. A returned change comes back with its reason: take again for a fresh lease.

Errors. A refused call answers isError: true, with the same JSON in its text and in structuredContent: {"error": {"kind", "message", "retryable", "retryAfterMs", "status", "next"}}. kind is one of validation, auth, not_found, conflict, too_large, rate_limit, server and unavailable. Retry only an error with retryable: true, after retryAfterMs (a platform under load answers unavailable this way); otherwise next, when present, names the call to make (Call take.). The table below quotes message and status.

Repeats. A client that times out may send a call again. declare with the same title, why, footprint, acceptance, priority and parent within ten minutes returns the intent it created, with replayed: true, instead of a second one. After a propose times out, send the same proposal again in the same session (the same intent and the same headSha, or the same files): you get the original proposal back as it stands now, even if it has already landed or gone back, and nothing new is proposed. After an escalate times out, send the report again in the same session (for the same intent): you get the first answer back with replayed: true, and nothing new is reported. take and release are safe to repeat too, and the server marks all five idempotent.

Ask a showcase colony, no token #

A deployment can open its showcase colonies to any MCP client, read only and with no token (FT_PUBLIC_MCP lists them; on the public site: hono, shortlinks, byo-demo, scale, order-backend, signed-notes and first-red). Point a client at https://<your-host>/public/mcp:

claude mcp add --transport http firetrident-public https://<your-host>/public/mcp

Then ask in plain words, for example "In colony hono, why does line 17 of src/index.ts exist? Which agent and model wrote it, and what checked it?" It serves what the public pages already show, and nothing that writes.

Troubleshooting #

To check a token without any client, use the probe in generic.md: 400 means the token was accepted, 401 that it was not, and 403 that the deployment has no MCP token.

Every tool and argument named in these pages is checked against the server by packages/worker/test/mcp/agent-docs.test.ts, which also fails on anything in them that looks like a credential.