Skip to content

Calling the server

You can call every method the server serves in three ways: over XRPC, as a command of the pds CLI, and as a tool on its MCP endpoint. All three take the same arguments and give the same answer.

The tool and the command names come from the method’s lexicon (Commands: every method as an MCP tool and a CLI command). For example, com.atproto.repo.createRecord is the tool repo_create_record and the command pds repo create-record. Its arguments are the tool’s arguments, or the command’s flags. So a method added to the server becomes a tool and a command at once.

When a method names an account (repo, for example), the tool and the command can leave it out, and then it’s the token’s account.

The methods are under /xrpc/, like on any atproto PDS:

curl https://pds.example.com/xrpc/com.atproto.server.describeServer

pds <group> <command> [flags] calls a running server. It reads three variables:

VariableWhat it does
PDS_URLThe server’s base URL.
PDS_TOKENA bearer token to send, if it’s set.
PDS_ADMIN_PASSWORDWhen there’s no PDS_TOKEN, the admin’s password, sent as Basic with the user admin.

Sign in, keep the access token, and call:

export PDS_URL=https://pds.example.com
export PDS_TOKEN=$(pds server create-session --identifier alice.pds.example.com --password … | jq -r .accessJwt)
pds repo create-record --collection com.example.note --record '{"text":"hi"}'
pds repo list-records --collection com.example.note --limit 5

pds --help lists the groups and commands, and pds <group> --help lists a group’s, each with its lexicon’s description. pds admin logs and pds admin stats (and the MCP tools admin_logs and admin_stats) are how the admin reads the log and the metrics, which have no lexicon (Commands: every method as an MCP tool and a CLI command, Operating).

An account lists and ends its OAuth sessions (the apps it signed in to) and the browsers it’s signed in on with its own password session (OAuth: the account's own sessions and devices). An app password or an OAuth token can’t do this. These commands do what the reference’s account pages do:

pds oauth sessions # each session's id, client, scope
pds oauth revoke-session --id <id> # sign that app out
pds oauth devices # each browser's id, user agent, IP
pds oauth revoke-device --id <id> # sign the account out of it

The matching MCP tools are oauth_sessions, oauth_revoke_session, oauth_devices and oauth_revoke_device.

You add, list and remove passkeys the same way, with the password session (Passkeys). pds passkey add answers with a link that’s good for 15 minutes. Open it in a browser on the device that’ll hold the passkey. After that, the account signs in on the authorization page with Sign in with a passkey, with no password and no email code:

pds passkey add --name Laptop # {"url": ".../oauth/passkey?token=…", "expiresAt": …}
pds passkey list # each passkey's id, name, when added and last used
pds passkey remove --id <id> # it no longer signs in

The matching MCP tools are passkey_list, passkey_add and passkey_remove. Treat the link as a secret, since whoever opens it in time adds a passkey to the account.

A few commands send or write bytes instead of JSON (Commands: every method as an MCP tool and a CLI command). sync get-repo and sync get-blob write the CAR file or blob to standard output. repo upload-blob --encoding <type> sends standard input as the blob, and repo import-repo sends standard input as a CAR file. That means you can move a repository from one server to another when the account moves, each side with its own PDS_URL and PDS_TOKEN (Moving an account between servers):

PDS_URL=$OLD PDS_TOKEN=$OLD_TOKEN pds sync get-repo --did "$DID" \
| PDS_URL=$NEW PDS_TOKEN=$NEW_TOKEN pds repo import-repo

pds xrpc makes any call by name, with goat xrpc’s arguments (Commands: every method as an MCP tool and a CLI command). k==v is a query parameter, k=v a string property of the body, k:=json any other property, Name:value a header, and - sends standard input as the body. It reaches methods that have no command, such as one the server forwards to the AppView, and it checks nothing before sending:

pds xrpc query app.bsky.actor.getProfile actor==atproto.com
pds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={"text":"hi"}'

POST /mcp is an MCP endpoint over Streamable HTTP, and it serves only tools (Commands: every method as an MCP tool and a CLI command). It serves clients of either era of MCP. That’s the stateless revision 2026-07-28 and, after an initialize, the legacy 2025-11-25 and 2025-06-18 that most clients still speak.

It takes Authorization: Bearer <token> with any token XRPC takes or an MCP client’s OAuth access token. It also takes the admin’s Basic. Every caller sees every tool listed, with a token or without.

Each tool has a title, and its annotations say what it does (Commands: every method as an MCP tool and a CLI command). A read is readOnlyHint, and a call that may delete, replace or end something is destructiveHint. So a client asks before those, but not before a read or a new record.

An MCP client such as Claude signs in by OAuth, the way MCP’s authorization spec describes (OAuth for MCP clients). The server’s root page, GET /, says how:

  1. Add <your server's URL>/mcp to the app as a connector. In Claude, go to Settings > Connectors > Add custom connector, and choose “Sign in when needed”.
  2. When it asks, sign in on the server’s page and approve it.
  3. Ask it things, like “What have I posted this week?”

The client finds the server’s MCP issuer from the endpoint’s metadata, and the token it gets is only for /mcp. Claude can only reach a server on the internet, so you’ll need a server deployed the way Deploying describes.