chadtmiller.com/monolith
An atproto PDS
0
0
# Commands: every method as an MCP tool and a CLI command
The server's methods are made for agents to call. An agent may call one over
XRPC, as a tool through the server's MCP endpoint, or as a command of the
`pds` CLI; each of the three is the same call, with the same arguments and
the same answer. The tools and the commands are not written one by one: they
are made from the lexicons in `lexicons/`, so a method the server serves is a
tool and a command as soon as it is served. The admin's two reads
(`OPERATIONS.md`, "The admin's reads"), the account's four routes for
its OAuth sessions (`OAUTH-ACCOUNT.md`) and its three for its passkeys
(`PASSKEYS.md`), which have no lexicon, are the exceptions: their tools
and commands are given below, in "The admin's reads", "The account's
OAuth sessions" and "The account's passkeys". This page says what they
are and how they are checked; `PDS.md` and the pages it links are the
rest of the server, and what they say still holds.
## One binary
The server and the CLI are one program, `pds`:
- `pds serve` runs the server, configured by the environment as `PDS.md`
says. When it cannot start, as when its data does not recover, it exits 1
with why on standard error.
- `pds migrate-blobs --to bucket|disk` moves the data directory's blobs
into the bucket or out of it, given the same environment, while no
server runs on it (`BLOBS.md`, "Moving them").
- `pds serve` and `pds migrate-blobs` each hold the data directory while
they run: one started on a data directory another holds exits 1, with
why on standard error, before it writes anything to standard output or
changes anything in it. A process killed lets it go.
- `pds <group> <command> [flags]` calls a method of a running server, and
`pds`, `pds --help` and `pds <group> --help` list the groups and commands,
each with its lexicon's description.
- `pds xrpc <query|procedure> <name> [args]` calls any method or route of a
running server by its name, as "Any call" says.
## Names
Each method the server serves has a group and a name, from its NSID: the
group is the NSID's second-to-last segment, and the name its last, as
written. `com.atproto.repo.createRecord` is group `repo`, name
`createRecord`. Then:
| As | Of `com.atproto.repo.createRecord` | Rule |
| --- | --- | --- |
| MCP tool | `repo_create_record` | group, `_`, name in snake case |
| MCP tool's `title` | `Create record (repo)` | the name in words, the first capitalized, then the group in parentheses |
| CLI command | `pds repo create-record` | group, then name in kebab case |
| CLI flag of `swapCommit` | `--swap-commit` | each parameter or input property, kebab case |
| Tool argument of `swapCommit` | `swapCommit` | as the lexicon names it |
The name in words is its kebab case with each `-` a space, so that
`com.atproto.identity.getRecommendedDidCredentials`' title is `Get
recommended did credentials (identity)`. No two methods the server serves
may share a group and name, and no group is `xrpc`.
## Which methods
Every method the server serves has a CLI command. Every one whose answer is
`application/json`, or that answers nothing, as `deleteSession`, has an MCP
tool: so all but those whose answer is a CAR file, `com.atproto.sync.getRepo`,
`getBlocks` and `getRecord`; `com.atproto.sync.getBlob`, whose answer is a
blob's bytes; and `com.atproto.sync.subscribeRepos`, which is a stream.
`subscribeRepos` has no CLI command either.
Nor has a method whose input is not JSON an MCP tool: `com.atproto.repo.uploadBlob`,
whose input is any bytes, and `com.atproto.repo.importRepo`, whose input is a
CAR file. With `com.atproto.sync.getBlob`, whose answer is the blob's bytes,
no MCP tool uploads or reads blobs, or imports a repository; their commands
do.
## The admin's reads
`/xrpc/_logs` and `/xrpc/_stats` (`OPERATIONS.md`, "The admin's reads") are
no lexicon's methods, so their tools and commands are written here rather
than made, and are otherwise as a method's: called with the same auth,
answering what the route answers, as "Answers" says, its errors as a
method's.
| Route | MCP tool | CLI command |
| --- | --- | --- |
| `_logs` | `admin_logs` | `pds admin logs` |
| `_stats` | `admin_stats` | `pds admin stats` |
They are in the group `admin`, after the commands of `com.atproto.admin`'s
methods, `logs` then `stats`, and listed after every lexicon's tool,
`admin_logs` then `admin_stats`. `admin_logs`'s arguments are
`_logs`'s parameters, `trace`, `msg`, `method`, `level`, `minMs` and
`limit`, none required, its `inputSchema`:
| Argument | Type | CLI flag |
| --- | --- | --- |
| `trace`, `msg`, `method` | `string` | `--trace`, `--msg`, `--method` |
| `level` | `string`, `enum` `debug`, `info`, `warn`, `error` | `--level` |
| `minMs` | `integer`, `minimum` 0 | `--min-ms` |
| `limit` | `integer`, `minimum` 1, `maximum` 500 | `--limit` |
`admin_stats` takes none: its `inputSchema` is an object with no
properties, and `pds admin stats` no flag. Both tools have `readOnlyHint:
true`, and a `title` by the rule of "Names", of their commands' names:
`Logs (admin)` and `Stats (admin)`. Their descriptions, the tools' and the
commands' in `--help`:
- `admin_logs`: "As the admin, the lines the server logged and kept in
PDS_LOG_DIR, oldest first: the last of those of a trace, a message, a
route, a level and above, or a time. Needs the admin's Basic auth."
- `admin_stats`: "As the admin, what the server counted since it started:
its requests by route and status with their mean times, the requests it
made, its syncs, its accounts and its firehose. Needs the admin's Basic
auth."
## The account's OAuth sessions
`OAUTH-ACCOUNT.md`'s four routes are no lexicon's methods either, so their
tools and commands are written here, and are otherwise as a method's, as
the admin's reads are: called with the same auth, answering what the route
answers, its errors as a method's.
| Route | MCP tool | CLI command | Arguments |
| --- | --- | --- | --- |
| `_oauthSessions` | `oauth_sessions` | `pds oauth sessions` | none |
| `_oauthRevokeSession` | `oauth_revoke_session` | `pds oauth revoke-session` | `id` |
| `_oauthDevices` | `oauth_devices` | `pds oauth devices` | none |
| `_oauthRevokeDevice` | `oauth_revoke_device` | `pds oauth revoke-device` | `id` |
They are the group `oauth`, listed after every other group, its commands
in the order above, and their tools after the admin's reads, in the same
order. A tool with no arguments has an `inputSchema` that is an object with
no properties, and its command no flag; `id` is a `string`, required, the
flag `--id`. `oauth_sessions` and `oauth_devices` have `readOnlyHint:
true`; `oauth_revoke_session` and `oauth_revoke_device` `readOnlyHint:
false` and `destructiveHint: true`. Their titles are by the rule of
"Names", of their commands' names: `Sessions (oauth)`, `Revoke session
(oauth)`, `Devices (oauth)` and `Revoke device (oauth)`. Their
descriptions, the tools' and the commands' in `--help`:
- `oauth_sessions`: "The OAuth sessions of your account, the apps you
signed in to, newest first: each with its id, client, issuer (atproto
or mcp), scope, and when it started, was last refreshed and ends. Needs
your account's password session."
- `oauth_revoke_session`: "End one of your account's OAuth sessions by its
id, as oauth_sessions lists it: the app is signed out at once. Needs
your account's password session."
- `oauth_devices`: "The browsers your account is signed in on through the
OAuth sign-in page, newest sign-in first: each with its id, when it
signed in, and its user agent and IP address. Needs your account's
password session."
- `oauth_revoke_device`: "Sign your account out of one browser by its id,
as oauth_devices lists it. Its apps' sessions stay: end those with
oauth_revoke_session. Needs your account's password session."
## The account's passkeys
`PASSKEYS.md`'s three routes are no lexicon's methods either, and their
tools and commands are as those of "The account's OAuth sessions" are.
| Route | MCP tool | CLI command | Arguments |
| --- | --- | --- | --- |
| `_passkeyList` | `passkey_list` | `pds passkey list` | none |
| `_passkeyAdd` | `passkey_add` | `pds passkey add` | `name` |
| `_passkeyRemove` | `passkey_remove` | `pds passkey remove` | `id` |
They are the group `passkey`, listed after `oauth`, its commands in the
order above, and their tools after the `oauth_` tools, in the same order.
`passkey_list`'s `inputSchema` is an object with no properties, and its
command has no flag; `name` is a `string`, required, with `minLength` 1
and `maxLength` 64, the flag `--name`; `id` is a `string`, required, the
flag `--id`. `passkey_list` has `readOnlyHint: true`; `passkey_add`
`readOnlyHint: false` and `destructiveHint: false`; `passkey_remove`
`readOnlyHint: false` and `destructiveHint: true`. Their titles are by the
rule of "Names", of their commands' names: `List (passkey)`, `Add
(passkey)` and `Remove (passkey)`. Their descriptions, the tools' and the
commands' in `--help`:
- `passkey_list`: "The passkeys of your account, newest first: each with
its id, name, when it was added and last signed in, and whether it is
backed up. Needs your account's password session."
- `passkey_add`: "A link to open in a browser within 15 minutes, which
adds a passkey of this name to your account: it then signs in on the
OAuth sign-in page with no password. A new link ends the last. Needs
your account's password session."
- `passkey_remove`: "Remove one of your account's passkeys by its id, as
passkey_list lists it: it no longer signs in. Needs your account's
password session."
## Arguments
A method's arguments are its lexicon's: a query's `parameters`, or a
procedure's `input` schema's properties. Where a required one names an
account, as `repo` and `did` do, it may be left out when a token is given,
and is then the token's account's DID: the server fills it in for a tool,
and the CLI asks the server with `getSession`. With no token, it is
required. An optional one, such as `createAccount`'s `did`, is never filled
in.
- **MCP.** A tool's `inputSchema` is a JSON Schema object whose properties
are the method's arguments, each typed from its lexicon: `string`,
`integer` and `boolean` as themselves, with `minimum`, `maximum`,
`maxLength` and `enum` where the lexicon has them; `array` as `array`,
with `maxItems` the lexicon's `maxLength` where it has one;
`unknown`, `object`, `ref` and `union` as any JSON value of their kind
(`object`, or no constraint for `unknown`), and `bytes`, `cid-link` and
`blob` with no constraint, as `unknown`; an argument the lexicon lists
as `nullable` has the type and `"null"`, as `["string", "null"]`; and its
`required` the lexicon's, less `repo` and `did`. A tool's `description` is
the lexicon's, its `title` as "Names" gives it, and its annotations as
"Hints" says.
- **CLI.** Each argument is a flag. A `string` flag takes its text, an
`integer` its digits, a `boolean` `true` or `false` (a bare boolean flag is
`true`). Any other takes JSON: `--record '{"text":"hi"}'`, and `-` for its
value reads the JSON from standard input. An argument cannot be given as
`null` this way: one whose value is `null` is passed over XRPC or MCP. A
flag the method does not take, a missing required one, or one that does
not parse is a usage error: exit status 2, with what was wrong on standard
error, and no call made.
## Hints
Each tool's `annotations` say what its call does, as MCP's tool
annotations do (`mcp/server/tools.md`): `readOnlyHint` whether it changes
nothing, and for one that changes something, `destructiveHint` whether it
may delete, replace or end what was there rather than only add. A client
may run a read-only tool without asking, and ask before a destructive one,
so they are given by what each method does, not by whether it is a query:
- A query has `readOnlyHint: true`, but for those that sign a token for
the account, `com.atproto.server.getServiceAuth` and
`com.atproto.space.getDelegationToken`: `readOnlyHint: false` and
`destructiveHint: false`.
- A procedure has `readOnlyHint: false`, and `destructiveHint: false` if
it only adds: `com.atproto.server.createAccount`, `createSession`,
`createAppPassword`, `createInviteCode`, `createInviteCodes`,
`requestEmailConfirmation`, `confirmEmail`, `requestEmailUpdate`,
`requestPasswordReset`, `requestAccountDelete`, `activateAccount`;
`com.atproto.identity.requestPlcOperationSignature`,
`signPlcOperation`; `com.atproto.repo.createRecord`;
`app.bsky.notification.registerPush`; and `com.atproto.space.createSpace`,
`createRecord`, `authorizeSpaceSync` and `notifyRepoUpdate`. Every other
procedure has `destructiveHint: true`: it may delete or replace a record,
a repository, a space or its members, or end a session, an app password,
a push registration or an account, or change its handle, email,
password, preferences, status or DID document.
*Note:* a procedure is destructive unless this list names it, so one the
server comes to serve is asked about until it is added here.
## Auth
- **MCP.** `POST /mcp` takes `Authorization: Bearer <token>`, the same
tokens XRPC takes, an MCP session's access token (`OAUTH-MCP.md`), or the
admin's `Basic` (`LIMITS.md`), and passes it to the method as XRPC does:
a tool answers a token the server did not give out, or no token, as its
method answers it over XRPC, but where `OAUTH-MCP.md` answers an HTTP
`401` challenge instead, so that a client signs in. Every tool is listed
to every caller, with a token or without.
- **CLI.** `PDS_URL` is the server's base URL, and `PDS_TOKEN`, if set, its
bearer token, sent as XRPC takes it. With `PDS_ADMIN_PASSWORD` set and
`PDS_TOKEN` not, a command sends `Authorization: Basic` with the user
`admin` and that password instead, as `createInviteCode` takes it
(`LIMITS.md`). `pds server create-session
--identifier … --password …` prints the session, whose `accessJwt` is a
token.
The CLI's variables, then:
| Variable | Is |
| --- | --- |
| `PDS_URL` | the server's base URL |
| `PDS_TOKEN` | a bearer token to send, if set |
| `PDS_ADMIN_PASSWORD` | with no `PDS_TOKEN`, the admin's password, sent as `Basic` with the user `admin` |
## Answers
- **MCP.** A tool's answer is its method's JSON answer as
`structuredContent`, with the same JSON in a `TextContent` block; for a
method that answers nothing, as `deleteSession`, it is `{}`. An error
the method answers is a tool execution error (`isError: true`) whose
`structuredContent` is `{error, message}`, as XRPC names them; arguments
the method refuses are such an error, as XRPC answers them. Only a tool
not listed, or a `tools/call` that MCP's `CallToolRequest` schema refuses
(no `name`, or `arguments` that is not an object), is the protocol error
`-32602`.
- **CLI.** A command prints its method's JSON answer on standard output, one
line, and exits 0; for a method that answers nothing, it prints `{}`. A
command whose answer is a CAR file, as `get-repo`'s is, writes the file's
bytes. An error the
method answers is printed on standard output as `{status, error,
message}`, with the HTTP status, and the command exits 1. A server that
cannot be reached is exit status 3, with why on standard error.
`get-blob` writes the blob's bytes, as `get-repo` does. `upload-blob`
sends standard input as the body, with `--encoding` as its
`Content-Type`; without `--encoding` it is a usage error. `import-repo`
sends standard input as the body, as `application/vnd.ipld.car`, so that
`pds sync get-repo --did <did> | pds repo import-repo` moves a
repository between two servers, each its own `PDS_URL` and
`PDS_TOKEN`.
## Any call
`pds xrpc <kind> <name> [args]` makes one XRPC call of the server at
`PDS_URL` by its name, with the auth of "Auth": a method the server
serves, one it forwards (`PROXY.md`), or one of its own routes, as
`_logs` or `_oauthSessions`. It is `goat xrpc`'s command, with its
arguments, but for its service, which is always `PDS_URL`; it knows no
lexicon, fills in nothing, and checks no argument against one, so the
server answers what is wrong with a call. It has no MCP tool.
| Argument | Is |
| --- | --- |
| `<kind>` | `query` (or `get`), a `GET`; `procedure` (or `post`), a `POST`; in any case |
| `<name>` | an NSID, or a route of the server's own, `_` then letters |
| `key==value` | a query parameter; given again, one more value of it |
| `key=value` | a string property of the JSON body |
| `key:=json` | a property of the JSON body, any JSON |
| `Name:value` | a request header; `Authorization` given so replaces the CLI's |
| `-` | the body, standard input as it comes, with the `Content-Type` a header gives |
| `@path` | a JSON object read from the file, its properties the body's before any given after it |
An argument is read at its first `:` or `=`: `==` makes a parameter,
`:=` a JSON property, a lone `=` a string property and a lone `:` a
header. A procedure's body is `-`'s, or otherwise the JSON object of its
properties, `{}` with none, as `application/json` unless a header names
another `Content-Type`; a query has none. A kind or name of another form
(an NSID as `atproto/nsid.md` defines one, or `_` and one or more
letters), an argument of none of these forms or with nothing before its
separator, a header name or value HTTP cannot carry, JSON that does not
parse, a body property, `@path` or `-` given to a query, `-` given twice
or beside body properties or `@path`, and an `@path` that cannot be read
or is not a JSON object are usage errors: exit status 2, with what was
wrong on standard error, and no call made. `--help` among the arguments
prints how it is called, exit 0, and makes no call.
It answers as a command does ("Answers"): a JSON answer printed on one
line, and an answer with no body `{}`, exit 0; an answer of another
`Content-Type` written as its bytes; an error printed as `{status, error,
message}`, exit 1; and a server that cannot be reached, exit 3.
```sh
pds xrpc query com.atproto.repo.listRecords repo==alice.test collection==app.bsky.feed.post limit==5
pds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={"text":"hi"}'
pds xrpc query _oauthSessions
pds xrpc procedure com.atproto.repo.uploadBlob Content-Type:image/png - < cat.png
pds xrpc query app.bsky.actor.getProfile actor==atproto.com Atproto-Accept-Labelers:did:plc:ar7c4by46qjdydhdevvrndac
```
## The MCP endpoint
`POST /mcp` on the server's port is a Streamable HTTP endpoint for MCP,
declaring only the `tools` capability. It is dual-era, as
`mcp/basic/versioning.md` names it ("Backward Compatibility with
Initialization-Based Versions"): it serves the modern revision
`2026-07-28` (`mcp/`) and the legacy revisions `2025-11-25` and
`2025-06-18` (`mcp/legacy/<version>/`), so that a client of either era
can use it. A request is served in the era it opens:
- **Modern.** A request whose `_meta` names a protocol version is served
statelessly as `2026-07-28` says: `server/discover`, `tools/list` and
`tools/call`, with no `initialize` and no session. What the endpoint
checks of such a request, its method, headers, `Origin` and protocol
version, and the errors it answers when they are wrong, are the
transport's (`mcp/basic/transports/streamable-http.md`) and
`mcp/basic/versioning.md`'s. A request with neither `_meta`'s version, a
legacy `MCP-Protocol-Version`, nor the method `initialize` is held to the
modern rules, and so refused: the server takes no client of `2025-03-26`,
which sent no such header.
- **Legacy.** An `initialize` request, whatever its headers, is answered as
`mcp/legacy/2025-11-25/basic/lifecycle.md` says: with the
`protocolVersion` the client asked for if it is `2025-11-25` or
`2025-06-18`, and `2025-11-25` otherwise; the capabilities `{tools:
{}}`; `serverInfo` and `instructions` as `server/discover` gives them.
The server assigns no session: it sends no `MCP-Session-Id`, and ignores
one sent. Every later request names its version in the
`MCP-Protocol-Version` header, and is served as that revision's
transport (`basic/transports.md`) and `schema.json` say, statelessly:
`ping` answers `{}`; `tools/list` and `tools/call` answer as in the
modern era, the same tools, schemas and results, in that revision's
shape; a notification, `notifications/initialized` among them, is `202
Accepted` with no body; any other method is `-32601`. Each answer is
HTTP `200`, its JSON-RPC error in it if any, but for what the transport
makes an HTTP error: an `Origin` it refuses is `403`, and an
`MCP-Protocol-Version` that names neither legacy revision nor
`2026-07-28` is `400` with an `UnsupportedProtocolVersionError`.
- In either era, `GET` and `DELETE` on `/mcp` are `405 Method Not
Allowed`: the server opens no stream of its own and keeps no session to
end. `server/discover`'s `supportedVersions`, and the `supported` of
every `UnsupportedProtocolVersionError`, are `2026-07-28`, `2025-11-25`
and `2025-06-18`, in that order.
MCP's authorization, the OAuth sign-in of an MCP client and the bearer
token it calls the endpoint with, is `OAUTH-MCP.md`'s.
## How it is checked
`node compare.mjs --commands -- <pds> serve` sends some of its requests through
the MCP tool, the CLI command for the method, or `pds xrpc`, instead of
XRPC, and holds their answers to the reference's, as for XRPC; the MCP
answers and CLI output are turned back into status and JSON as above. A
tool call goes in either era, at random: modern, or legacy as `2025-11-25`
or `2025-06-18`. `pds xrpc` sends its arguments in each of their forms
that the request allows: parameters as `==`, properties as `=` or `:=` or
an `@path` file, a body as `-` where its input is not JSON. As well:
- `tools/list` must list exactly the tools above, named as above, and each
tool's `inputSchema` must have exactly the lexicon's properties, typed as
above, with the required ones above, `admin_logs` and `admin_stats`
as "The admin's reads" gives them, the four `oauth_` tools as "The
account's OAuth sessions" gives them, and the three `passkey_` tools as
"The account's passkeys" gives them; each tool's `title` as "Names"
gives it, and its `readOnlyHint` and `destructiveHint` as "Hints" gives
them; in each legacy revision, the same
tools as in the modern era. Every MCP message must be valid against the
`schema.json` of its era's revision. `admin_logs` and `admin_stats`, and
`pds admin logs` and `pds admin stats`, with the admin's auth, with a
token, and with none, must answer as `_logs` and `_stats` do; each
`oauth_` tool and its command, with an account's password token, an app
password's, and none, as its route does (`OAUTH-ACCOUNT.md`, "How it is
checked"); and each `passkey_` tool and its command likewise
(`PASSKEYS.md`, "How it is checked").
- `pds xrpc` of each of the server's own routes, with the auth each
takes, must answer as the route does; of a method the server forwards,
as XRPC does; and each usage error above must exit 2, with no request
reaching the server.
- `server/discover` must name the three versions. For each legacy
revision, `initialize` with and without `MCP-Protocol-Version` must
answer that revision, with the tools capability, the server's identity
and instructions, and no `MCP-Session-Id`; asking for `2025-03-26` or a
version no revision has must answer `2025-11-25`. Then
`notifications/initialized` must be `202` with no body; `ping`, `{}`;
`server/discover` with a legacy header, `-32601`; an unknown tool,
`-32602`. A request with no version anywhere must be `400` with
`-32020`, and an `MCP-Protocol-Version` of `2025-03-26`, `400` with
`-32022` and the three versions. `GET` and `DELETE` on `/mcp` must be
`405`.
- `pds <group> --help` must list exactly the group's commands, and `pds
<group> <command> --help` its flags; a flag it does not take, and a
command it does not have, must be usage errors.
- `node conformance.mjs -- <pds> serve` runs MCP's conformance suite against
the endpoint, anonymously, for the scenarios that need none of the suite's
own test tools: those of `2026-07-28`, and the legacy ones of `2025-11-25`
(`server-initialize`, `server-session-lifecycle`, `ping`, `tools-list`
and `dns-rebinding-protection`). `harness/conformance.yaml` names each
check within them the server cannot pass by design, and why: those that
need the suite's own tools, and the one for a server that does not
implement `initialize`.