# 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. ## Names The tool and the command names come from the method's lexicon ([COMMANDS.md](../../spec/COMMANDS.md#names)). 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. ## XRPC The methods are under `/xrpc/`, like on any atproto PDS: ```sh curl https://pds.example.com/xrpc/com.atproto.server.describeServer ``` ## The CLI `pds [flags]` calls a running server. It reads three variables: | Variable | What it does | | --- | --- | | `PDS_URL` | The server's base URL. | | `PDS_TOKEN` | A bearer token to send, if it's set. | | `PDS_ADMIN_PASSWORD` | When there's no `PDS_TOKEN`, the admin's password, sent as `Basic` with the user `admin`. | Sign in, keep the access token, and call: ```sh 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 --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.md](../../spec/COMMANDS.md#the-admins-reads), [Operating](operating.md#reading-the-log-and-stats)). 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-ACCOUNT.md](../../spec/OAUTH-ACCOUNT.md)). An app password or an OAuth token can't do this. These commands do what the reference's account pages do: ```sh pds oauth sessions # each session's id, client, scope pds oauth revoke-session --id # sign that app out pds oauth devices # each browser's id, user agent, IP pds oauth revoke-device --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.md](../../spec/PASSKEYS.md)). `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: ```sh 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 # 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.md](../../spec/COMMANDS.md#answers)). `sync get-repo` and `sync get-blob` write the CAR file or blob to standard output. `repo upload-blob --encoding ` 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` ([MIGRATION.md](../../spec/MIGRATION.md)): ```sh 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.md](../../spec/COMMANDS.md#any-call)). `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: ```sh 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"}' ``` ## MCP `POST /mcp` is an MCP endpoint over Streamable HTTP, and it serves only tools ([COMMANDS.md](../../spec/COMMANDS.md#the-mcp-endpoint)). 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 ` 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.md](../../spec/COMMANDS.md#hints)). 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. ## Connect an AI app An MCP client such as Claude signs in by OAuth, the way MCP's authorization spec describes ([OAUTH-MCP.md](../../spec/OAUTH-MCP.md)). The server's root page, `GET /`, says how: 1. Add `/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](deploying.md) describes.