Quick start for agents
How an AI agent connects to Termbanks, what it can do without an account, and the rules it must follow. Agents can read this page as Markdown at /help/agents.md.
Connect
- MCP server (Streamable HTTP) at
/mcp/. Public tools work without an account; OAuth 2.1 starts when a tool needs one. - Clients that cannot use OAuth send
Authorization: Bearer tb_…with a token a person issued in Connected agents. - Call
whoamifirst: it returns your level, grants and the collections you may use, or the anonymous limits with sign-up links. - Account creation, sign-in and consent happen only in a person's browser, never in chat.
Without an account
Anonymous agents can read the public bank, rate-limited per address (60 requests per 15 minutes by default). Past the limit they get HTTP 429 anonymous_limit_reached with register_url and sign_in_url to pass on to the person.
| To | MCP tool | REST |
|---|---|---|
| Translate with the bank's terms fixed in place | pin_terms, then unpin_terms | POST /api/v1/terms/pin, POST /api/v1/terms/unpin |
| Look up translations for up to 500 terms | terms_lookup | POST /api/v1/terms/lookup |
| Find known terms in a document | terms_find_in_text | POST /api/v1/terms/find-in-text |
| Check a translation against the terms | translation_check | POST /api/v1/translations/check |
| Pick the preferred term for a word | resolve_term | POST /api/v1/resolve |
| Search public concepts | search_public_concepts | GET /api/v1/public/search |
| Fetch the public terms for a task | sync_pull without a collection | POST /api/v1/public/sync/pull |
Reading pages as Markdown
Every page on this site has a Markdown version: send Accept: text/markdown, or add .md to the path (/index.md for the home page). Private pages need the same credential as the page. The index for agents is at /llms.txt.
Rules every agent follows
- Pushes are staged, never written directly. A person, or an agent they allowed, commits them.
- Absence never deletes; only
withdrawn: truewithdraws a term. - Public terms are never changed in place. A change to one becomes a collection override, a proposal or a contribution.
- Keep original spelling, BCP 47 tags, sources and licenses exactly as given.
- Never merge concepts. Suggest a merge and let a person decide.
- Previously reviewed terms can be changed only when the credential permits overrides. New unrestricted role delegation includes this capability; read-only and proposal-only restrictions do not.
Ready-made workflows
The MCP server offers three prompts: prepare_glossary, translate_with_termbank and maintain_collection. They are described in Translation workflows.