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, “The admin’s reads”), the account’s four routes for
its OAuth sessions (OAuth: the account's own sessions and devices) and its three for its passkeys
(Passkeys), 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; The PDS: accounts and their records and the pages it links are the
rest of the server, and what they say still holds.
One binary
Section titled “One binary”The server and the CLI are one program, pds:
pds serveruns the server, configured by the environment as The PDS: accounts and their records 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|diskmoves the data directory’s blobs into the bucket or out of it, given the same environment, while no server runs on it (Blobs, “Moving them”).pds serveandpds migrate-blobseach 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, andpds,pds --helpandpds <group> --helplist 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.
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
Section titled “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
Section titled “The admin’s reads”/xrpc/_logs and /xrpc/_stats (Operations, “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
Section titled “The account’s OAuth sessions”OAuth: the account's own sessions and devices’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
Section titled “The account’s passkeys”Passkeys’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
Section titled “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
inputSchemais a JSON Schema object whose properties are the method’s arguments, each typed from its lexicon:string,integerandbooleanas themselves, withminimum,maximum,maxLengthandenumwhere the lexicon has them;arrayasarray, withmaxItemsthe lexicon’smaxLengthwhere it has one;unknown,object,refandunionas any JSON value of their kind (object, or no constraint forunknown), andbytes,cid-linkandblobwith no constraint, asunknown; an argument the lexicon lists asnullablehas the type and"null", as["string", "null"]; and itsrequiredthe lexicon’s, lessrepoanddid. A tool’sdescriptionis the lexicon’s, itstitleas “Names” gives it, and its annotations as “Hints” says. - CLI. Each argument is a flag. A
stringflag takes its text, anintegerits digits, abooleantrueorfalse(a bare boolean flag istrue). Any other takes JSON:--record '{"text":"hi"}', and-for its value reads the JSON from standard input. An argument cannot be given asnullthis way: one whose value isnullis 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.
Each tool’s annotations say what its call does, as MCP’s tool
annotations do (MCP's Tools spec): 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.getServiceAuthandcom.atproto.space.getDelegationToken:readOnlyHint: falseanddestructiveHint: false. - A procedure has
readOnlyHint: false, anddestructiveHint: falseif 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; andcom.atproto.space.createSpace,createRecord,authorizeSpaceSyncandnotifyRepoUpdate. Every other procedure hasdestructiveHint: 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.
- MCP.
POST /mcptakesAuthorization: Bearer <token>, the same tokens XRPC takes, an MCP session’s access token (OAuth for MCP clients), or the admin’sBasic(Limits), 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 for MCP clients answers an HTTP401challenge instead, so that a client signs in. Every tool is listed to every caller, with a token or without. - CLI.
PDS_URLis the server’s base URL, andPDS_TOKEN, if set, its bearer token, sent as XRPC takes it. WithPDS_ADMIN_PASSWORDset andPDS_TOKENnot, a command sendsAuthorization: Basicwith the useradminand that password instead, ascreateInviteCodetakes it (Limits).pds server create-session --identifier … --password …prints the session, whoseaccessJwtis a token.
The CLI’s variables, then:
| Variable | Description |
|---|---|
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
Section titled “Answers”- MCP. A tool’s answer is its method’s JSON answer as
structuredContent, with the same JSON in aTextContentblock; for a method that answers nothing, asdeleteSession, it is{}. An error the method answers is a tool execution error (isError: true) whosestructuredContentis{error, message}, as XRPC names them; arguments the method refuses are such an error, as XRPC answers them. Only a tool not listed, or atools/callthat MCP’sCallToolRequestschema refuses (noname, orargumentsthat 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, asget-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-blobwrites the blob’s bytes, asget-repodoes.upload-blobsends standard input as the body, with--encodingas itsContent-Type; without--encodingit is a usage error.import-reposends standard input as the body, asapplication/vnd.ipld.car, so thatpds sync get-repo --did <did> | pds repo import-repomoves a repository between two servers, each its ownPDS_URLandPDS_TOKEN.
Any call
Section titled “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 (Proxying, service auth and preferences), 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 | Description |
|---|---|
<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's Namespaced Identifiers (NSIDs) spec 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.
pds xrpc query com.atproto.repo.listRecords repo==alice.test collection==app.bsky.feed.post limit==5pds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={"text":"hi"}'pds xrpc query _oauthSessionspds xrpc procedure com.atproto.repo.uploadBlob Content-Type:image/png - < cat.pngpds xrpc query app.bsky.actor.getProfile actor==atproto.com Atproto-Accept-Labelers:did:plc:ar7c4by46qjdydhdevvrndacThe MCP endpoint
Section titled “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's Versioning and Compatibility spec 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
_metanames a protocol version is served statelessly as2026-07-28says:server/discover,tools/listandtools/call, with noinitializeand no session. What the endpoint checks of such a request, its method, headers,Originand protocol version, and the errors it answers when they are wrong, are the transport’s (MCP's Streamable HTTP spec) and MCP's Versioning and Compatibility spec’s. A request with neither_meta’s version, a legacyMCP-Protocol-Version, nor the methodinitializeis held to the modern rules, and so refused: the server takes no client of2025-03-26, which sent no such header. - Legacy. An
initializerequest, whatever its headers, is answered as MCP's Lifecycle spec (2025-11-25) says: with theprotocolVersionthe client asked for if it is2025-11-25or2025-06-18, and2025-11-25otherwise; the capabilities{tools: {}};serverInfoandinstructionsasserver/discovergives them. The server assigns no session: it sends noMCP-Session-Id, and ignores one sent. Every later request names its version in theMCP-Protocol-Versionheader, and is served as that revision’s transport (basic/transports.md) andschema.jsonsay, statelessly:pinganswers{};tools/listandtools/callanswer as in the modern era, the same tools, schemas and results, in that revision’s shape; a notification,notifications/initializedamong them, is202 Acceptedwith no body; any other method is-32601. Each answer is HTTP200, its JSON-RPC error in it if any, but for what the transport makes an HTTP error: anOriginit refuses is403, and anMCP-Protocol-Versionthat names neither legacy revision nor2026-07-28is400with anUnsupportedProtocolVersionError. - In either era,
GETandDELETEon/mcpare405 Method Not Allowed: the server opens no stream of its own and keeps no session to end.server/discover’ssupportedVersions, and thesupportedof everyUnsupportedProtocolVersionError, are2026-07-28,2025-11-25and2025-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 for MCP clients’s.
How it is checked
Section titled “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/listmust list exactly the tools above, named as above, and each tool’sinputSchemamust have exactly the lexicon’s properties, typed as above, with the required ones above,admin_logsandadmin_statsas “The admin’s reads” gives them, the fouroauth_tools as “The account’s OAuth sessions” gives them, and the threepasskey_tools as “The account’s passkeys” gives them; each tool’stitleas “Names” gives it, and itsreadOnlyHintanddestructiveHintas “Hints” gives them; in each legacy revision, the same tools as in the modern era. Every MCP message must be valid against theschema.jsonof its era’s revision.admin_logsandadmin_stats, andpds admin logsandpds admin stats, with the admin’s auth, with a token, and with none, must answer as_logsand_statsdo; eachoauth_tool and its command, with an account’s password token, an app password’s, and none, as its route does (OAuth: the account's own sessions and devices, “How it is checked”); and eachpasskey_tool and its command likewise (Passkeys, “How it is checked”).pds xrpcof 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/discovermust name the three versions. For each legacy revision,initializewith and withoutMCP-Protocol-Versionmust answer that revision, with the tools capability, the server’s identity and instructions, and noMCP-Session-Id; asking for2025-03-26or a version no revision has must answer2025-11-25. Thennotifications/initializedmust be202with no body;ping,{};server/discoverwith a legacy header,-32601; an unknown tool,-32602. A request with no version anywhere must be400with-32020, and anMCP-Protocol-Versionof2025-03-26,400with-32022and the three versions.GETandDELETEon/mcpmust be405.pds <group> --helpmust list exactly the group’s commands, andpds <group> <command> --helpits flags; a flag it does not take, and a command it does not have, must be usage errors.node conformance.mjs -- <pds> serveruns MCP’s conformance suite against the endpoint, anonymously, for the scenarios that need none of the suite’s own test tools: those of2026-07-28, and the legacy ones of2025-11-25(server-initialize,server-session-lifecycle,ping,tools-listanddns-rebinding-protection).harness/conformance.yamlnames 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 implementinitialize.