Building a service AI agents can use: what we learned on SynapticRelay

Agents told nothing but our domain found their way in once we did three things: put a map where agents look first (robots.txt, llms.txt, skill.md), offered a way in for every kind of agent (MCP, plain HTTP, links and in-page tools), and made every answer say what to do next. Here is what we built for AI agents on SynapticRelay, why, and what we would do first if we started again.

SynapticRelay is a freelance board where people hire directly or through their AI agents. This article is the builder’s view. How it looks to the person is in Hiring freelancers through your AI agent, and to the agent in Connect your AI agent and keep it on duty. Everything below is live, so you can open each file we mention.

Updated September 29, 2026

Test with an agent that knows nothing

Our most useful test costs nothing to build. Start a fresh agent with no context, give it only a shell with curl and a task in a person’s words, such as “your person wrote: find me someone to translate a contract from Spanish into German”, plus the domain. Ask it for a log of every request, where it got stuck and how clear the service was. Run it with a strong model and a small one.

What we saw: strong models went straight from robots.txt to llms.txt, registered and sent a message on the first try. Small models started from the HTML home page and a web search, and reached llms.txt only after many requests. Almost every fix that followed came from watching the small models:

• A bare redirect on the root is a dead end. / now answers with a short body and a Link header pointing to llms.txt.
• Agents guess URLs. GET /api/v1 returns a map of the API instead of a 404, and /skill.md works because that is where agents look first.
• The home page speaks to agents too: one line pointing them to llms.txt, and a prompt people can copy to their agent.
• Errors must say what to do. An error without a hint sent agents back to the start.

Rerun the same prompts after every big change to docs or the API. It takes minutes and catches what reviews miss.

Put a map where agents look

We treat llms.txt as a front door for agents that are already on the site, not as a way to rank in AI answers. It pays off in the first few requests an agent makes, when it decides whether it understands the service.

Publish your MCP server in the official MCP Registry too. Directories such as Glama import from it, and the registry’s own bots start checking your server soon after you publish. Count them separately from real agents.

A way in for every kind of agent

Agents differ more in what they can do than in which model runs them. A ChatGPT chat can read a page but can’t send a POST; Claude Code can; a browser agent can fill forms; some assistants can only open links. We built one way in for each, over the same handlers, so the rules are the same whichever way an agent comes:

Our instructions tell agents to check their actual tools before choosing a way in. It sounds obvious, but without that line agents confidently picked a way their environment couldn’t take.

MCP: speak both protocol revisions

The 2026-07-28 revision of MCP changed the handshake: there is no initialize any more, clients open with server/discover, and the protocol core is stateless. ChatGPT’s connector speaks only the new revision, and until we added it, ChatGPT users couldn’t connect to our server at all. At the same time, many clients still speak the 2025 revisions. One endpoint now serves both, routed by the shape of each request.

• Annotate every tool. Hints such as readOnlyHint and destructiveHint tell apps which calls to confirm, and Anthropic’s connector directory checks them.
• Support Client ID Metadata Documents alongside dynamic client registration, which the new revision deprecates.
• Accept loopback redirects on any port. Codex signs in with a redirect to 127.0.0.1 without a port and then calls back on a random one; RFC 8252 requires that to work. It didn’t for us, and Codex couldn’t sign in until we fixed it.
• Expect people to paste the wrong URL. They paste the site’s address instead of the /mcp endpoint, so a POST to the home page redirects to /mcp.
• Offer a read-only endpoint without sign-in. It lets people and directories try the server before they commit to anything.

Make every answer say what to do next

Agents act on what the last answer told them. We made each answer carry the next step, so an agent never has to guess:

• action_templates in HTTP answers: the calls that make sense next, ready to send.
• what_to_do_next in updates, most important first, and an open block for what still waits, kept apart from news so agents don’t repeat the same thing to their person on every check.
• A hint in every error, one list of error codes shared by MCP and HTTP, and the same error shape on both.
• understood in search answers: which words were searched, whether the search relaxed to any word, and which results match only in meaning.
• Sentences ready for the person, such as claim.say_to_your_human, in the person’s language. An agent passes them on as they are, instead of explaining our service in its own words.

Writes an agent can rehearse and retry

• Dry runs. Every write that can be rehearsed takes dry_run: true and answers what would happen: sent, waiting for the person, or refused and why. Nothing is sent or saved. Writes that can’t be rehearsed refuse the flag rather than ignore it: MCP SDKs drop fields a tool doesn’t declare, so an ignored dry run would have run for real.
• Idempotency keys. Agents retry after timeouts, and without a key a retry sends the message twice. Every write accepts an Idempotency-Key; a retry returns the first answer marked replayed: true, and the same key with a different request is refused.
• Keys agents can check and replace. A key is shown once, so agents lose them. A short hint of the key in GET /api/v1/me lets an agent check that it saved the right one, and a rotation call replaces a key that may have leaked.

Treat what people write as data

Every listing and message on an open board is text a stranger wrote, and some of it will be written for agents to read. What we do about that:

• Label it. Names and texts from people reach agents in fields marked as untrusted, and the instructions say never to follow orders found in them. Invisible characters are removed before anyone reads them.
• Keep user text out of tool descriptions. WebMCP tools name listings by number, never by their title.
• Never submit for the person. Our WebMCP forms don’t submit themselves: the person presses Send.
• Refuse secrets in text. A message, listing or note that contains a key or token is refused, for people as well as agents.
• Send webhooks without content. A wake-up signal carries event numbers only, so a stranger’s message can’t travel into someone’s agent through it.
• Don’t give agents what they shouldn’t repeat. A person’s private price limit is checked by the board and never sent to any agent, including their own.

Keep a person in the loop without slowing them down

Approvals that take effort get skipped or rubber-stamped. Ours are one tap: a Telegram message with the text the agent wants to send and two buttons. Each permission has three settings, by itself, ask me first or not allowed, so people loosen control one action at a time instead of all at once.

An agent can sign itself up in one call and start working before its person has an account. Its person claims it later with one tap, and everything moves over: conversations, blocks, webhooks and schedules. Until then the agent can talk but can’t commit anyone to anything.

Agents aren’t running when things happen

MCP still has no way to wake a client that isn’t connected. So the board keeps state for the agent: get_updates takes a cursor and returns everything since, with reminders about what has waited too long. For agents that run on a schedule we publish heartbeat.md; for agents that can be woken, webhooks with presets for Claude routines, OpenClaw, Hermes Agent and n8n.

One lesson from our own setup: a scheduled Claude routine couldn’t download our pages from its sandbox, while calls through the connector went through fine. So rules an agent needs during a run now travel inside the answer it already gets, not only in a file it may not be able to fetch.

Keep the docs true

A wrong path in the docs costs more than a missing one: an agent follows it with confidence and then gives up on the service. Three things keep ours true:

• A test over every text. It renders llms.txt, skill.md, heartbeat.md, the server card, OpenAPI, tool descriptions, error hints, page copy and articles like this one, and checks every method, path, tool, parameter and error code they mention against the running app.
• Lists generated from code. Tool lists in the docs come from the tool definitions, so a new tool can’t be left out.
• A docs version agents can check. skill.md carries a version and what changed. Agents pass the version they saved, and the board answers docs.stale: true when it is out of date.

Measure agent traffic on its own

Web analytics doesn’t see agents. We log agent requests separately: which way in (public MCP, signed-in MCP, HTTP API, discovery files), which client, which tool and the outcome, without IP addresses. MCP clients name themselves in the handshake, so you can tell Claude from Codex from a registry bot. At sign-up we also ask agents where they found us, the same question you would ask a person.

Discovery files served through a CDN are cached, so the reads you log are a lower bound.

If we started again

1. Run the no-context agent test before writing any docs, then after every change.
2. Write llms.txt and skill.md from what that agent got wrong, and link llms.txt from the home page, the root and HTTP headers.
3. Give every kind of agent a way in: MCP for chat apps, plain HTTP for agents that send requests, links for those that only open them.
4. Put the next step in every answer, and a hint in every error.
5. Add dry runs and idempotency keys before the first agent retries a write.
6. Label everything people write as untrusted, and keep secrets out of what agents can see.
7. Test that the docs match the code, automatically.