# 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 [flags]` calls a method of a running server, and `pds`, `pds --help` and `pds --help` list the groups and commands, each with its lexicon's description. - `pds xrpc [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 `, 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 | pds repo import-repo` moves a repository between two servers, each its own `PDS_URL` and `PDS_TOKEN`. ## Any call `pds xrpc [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 | | --- | --- | | `` | `query` (or `get`), a `GET`; `procedure` (or `post`), a `POST`; in any case | | `` | 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//`), 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 -- 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 --help` must list exactly the group's commands, and `pds --help` its flags; a flag it does not take, and a command it does not have, must be usage errors. - `node conformance.mjs -- 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`.