APIs and MCP
Everything you can do in the hub from your browser, a program can do as well. The hub has a REST API, which is how a program reaches it, and an MCP server, which is how an AI agent reaches it. Both lead to the same backend, so a program or an agent sees the same workspaces, documents and projects you do, and is held to the same permissions you are.
You do not need any of this to use the hub.
These pages are for when you want to write a program against it, give an agent a way in, or work with it from a terminal. The REST API is served by the backend and described by a live OpenAPI document. Ready-made SDKs and the adh command line wrap it. The MCP server listens at /mcp.
Topics
- The REST API: keys, addresses, and the OpenAPI document that lists every call.
- MCP: the tools an agent is handed, and the permissions each call runs under.
- SDKs and the command line: the generated libraries and the
adhcommand.
- Frameworks
- Next.js
Routes come from the database. A route's address starts with the schema its table is in, so a route cannot name a table that does not exist, and the OpenAPI document cannot describe a route that is not served.
The /api prefix belongs to the website. The backend serves bare paths. The prefix is the Next.js site's way of passing calls through to the backend, which is why the refresh cookie's path is /api/auth on the site and the backend never sees /api.
A scope allows nothing by default. A token reaches what its scope names and what the agent allowlist names, and nothing else. A scope of * means every route that can be scoped, which leaves out the routes that never can be.
An agent's call goes in through the front door. The gateway sends a call back through the hub's own request handling rather than straight to a handler, so a browser and an agent pass the same middleware, write the same usage record and leave the same audit trail.
A write is committed before it is acknowledged. A batch of tool calls runs one at a time, and each write is committed before its result goes back, so an agent never acts on a result that was later rolled back.
A new surface is a new scope, not a new kind of token. A new token family means a set of columns, a way to revoke it and a review. A scope is a string in a list.