~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
444 lines · 24.1 KB Raw History

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:

AsOf com.atproto.repo.createRecordRule
MCP toolrepo_create_recordgroup, _, name in snake case
MCP tool's titleCreate record (repo)the name in words, the first capitalized, then the group in parentheses
CLI commandpds repo create-recordgroup, then name in kebab case
CLI flag of swapCommit--swap-commiteach parameter or input property, kebab case
Tool argument of swapCommitswapCommitas 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.

RouteMCP toolCLI command
_logsadmin_logspds admin logs
_statsadmin_statspds 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:

ArgumentTypeCLI flag
trace, msg, methodstring--trace, --msg, --method
levelstring, enum debug, info, warn, error--level
minMsinteger, minimum 0--min-ms
limitinteger, 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.

RouteMCP toolCLI commandArguments
_oauthSessionsoauth_sessionspds oauth sessionsnone
_oauthRevokeSessionoauth_revoke_sessionpds oauth revoke-sessionid
_oauthDevicesoauth_devicespds oauth devicesnone
_oauthRevokeDeviceoauth_revoke_devicepds oauth revoke-deviceid

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.

RouteMCP toolCLI commandArguments
_passkeyListpasskey_listpds passkey listnone
_passkeyAddpasskey_addpds passkey addname
_passkeyRemovepasskey_removepds passkey removeid

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:

VariableIs
PDS_URLthe server's base URL
PDS_TOKENa bearer token to send, if set
PDS_ADMIN_PASSWORDwith 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.

ArgumentIs
<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==valuea query parameter; given again, one more value of it
key=valuea string property of the JSON body
key:=jsona property of the JSON body, any JSON
Name:valuea request header; Authorization given so replaces the CLI's
-the body, standard input as it comes, with the Content-Type a header gives
@patha 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.

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.