hosted instance
the easiest way to get started - no installation required:adding authentication
for write operations (create, update, delete), add your credentials:custom PDS
nothing extra to configure. pdsx resolves your account’s PDS from your handle’s DID document, so a self-hosted account authenticates with the same two headers as everyone else.this used to require an
x-atproto-pds-url header. it no longer does — authenticated
calls previously defaulted to bsky.social, which mints a token your own PDS rejects
with BadJwtSignature. the PDS is now discovered from your handle.x-atproto-pds-url still exists as an override, for pointing at a host that
differs from what your DID document names:
local/self-hosted
run the MCP server locally for development or self-hosting:configure claude code for local server
available tools
the MCP server exposes nine tools:permissioned data (
pdsx spaces …) is CLI only — there are no MCP tools for
com.atproto.space.* while the proposal is still experimental.read operations
read operations work without authentication when you specify arepo:
repo parameter, the server reads from your authenticated account.
get_record preserves the full record value, including facet byte ranges,
$type, language tags, and reply CIDs. list_records returns compact values:
facets become links/mentions, reply references become URI strings, and nulls,
$type, and English-only language tags are omitted. Use get_record when
inspecting the stored schema or preparing an edit.
list_records returns {results: [...], cursor: ...} with or without select.
Pass the returned cursor unchanged to read the next page; null marks the end
of a successful traversal. A jq filter can return no matches while the cursor
still points to another page.
Pages exceeding the response size limit return error: "response_too_large"
and retry_cursor instead of partial results. Reduce limit or narrow select
and retry with that cursor. No continuation cursor is returned for an oversized
page, so unseen records cannot be silently skipped by advancing past it.
The MCP read tools simplify record values. In post records, value.reply.parent
and value.reply.root are URI strings, not the original {uri, cid} objects.
write operations
write operations always require authentication:PDS discovery
pdsx automatically discovers the correct PDS for any user. when you query records fromrepo="zzstoatzz.io", it:
- resolves the handle to a DID
- looks up the DID document
- extracts the PDS endpoint
- queries that PDS directly
common collections
here are the most commonly used collections:prompts
the MCP server includes built-in prompts for guidance:usage_guide- general usage instructionscreate_post_guide- how to create posts with rich text
resources
the server exposes one resource:pdsx://me- shows your authenticated identity (handle and DID)
example workflows
reading someone’s recent posts
getting a user’s bio
creating a post
updating your bio
troubleshooting
”authentication required”
you’re trying to perform an operation that needs credentials:- write operations (create, update, delete) always need auth
- read operations without
repoparameter need auth
empty results for custom PDS users
if you’re getting empty results when querying a user on a self-hosted PDS, ensure you’re using a recent version of pdsx. older versions didn’t automatically discover custom PDS endpoints.”could not find repo”
the handle or DID couldn’t be resolved. check:- the handle is spelled correctly
- the account exists and isn’t deleted
- your network can reach the PDS
what’s next
- configure for writes - set up authentication
- read any repository - explore public data with the CLI
- addressing - understand AT-URIs and record addressing