RCSB MCP — an agent skill for the RCSB PDB MCP server

Drive the official RCSB PDB MCP server without guessing. 36 tools mapped, the search-then-batch call model, verified argument shapes, and the beta gaps written down.

RCSB PDB published a beta MCP server on 2026-10-14 (rcsb/rcsb-mcp) that fronts three real RCSB APIs — Search, Data, and Sequence Coordinates — plus EBI ontology resolvers. Querying the archive is strictly better than asking a model to remember it: a structure's resolution, its construct boundaries, and which UniProt residues it covers are facts you read from the API.

The server is good. Its documentation is not, and its argument shapes are not guessable. This skill is the map: what each tool does, how the layers chain, and every trap that costs a failed call the first time.

---

Why this exists

Everything below was found by driving the live server, not by reading its README.

Finding	Why it matters
The upstream README documents tools that no longer exist. It still advertises rcsb_search_fulltext, rcsb_search_by_attribute and group_by_identity; the search layer was rebuilt as rcsb_query_* + rcsb_search_request (group_by, not group_by_identity). The repo's own test comments admit the docs drifted for months.	Copying the README's tables produces "Unknown tool" errors. The live schemas are the only contract — so this skill ships a probe that reads them.
rcsb_search_request does not take a query — it takes an envelope. rcsb_query_* returns {query: {...}, digest: "..."}, and that whole object is the argument. Passing the inner query fails with two pydantic Field required errors.	Two failed calls before the shape is obvious.
A keyword search silently misses entries. Full-text "IGHMBP2" returns 3 entries; the R3H-domain structure 1MSZ is absent because it is titled Smubp-2.	"This protein has N structures" is wrong unless you also go through the UniProt cross-reference.
An entire tool is empty. rcsb_seqcoord_annotations returns zero annotations — verified against a PDB entity, against a UniProt accession, and against the README's own example. So the intended path of mapping disease variants onto structure residues does not work through it.	You would otherwise design a workflow around a tool that returns [] forever.
Unknown ids are reported, not raised. rcsb_get_* lists misses under not_found and count covers only the hits.	One typo in a batch quietly yields fewer rows instead of an error.
"Bogus" test ids are real. 9ZZZ is a real entry (a PARP2 nucleosome complex) and ZZZ is a real chemical component. Both error-path tests returned HTTP 200 and proved nothing.	Beware any negative test built on a plausible-looking PDB code.

---

Requirements

• Python ≥ 3.10 (the server's own floor — it imports mcp.server.fastmcp, and the mcp package must stay <2, because mcp 2.0 deleted FastMCP).
• uv available, so uvx rcsb-mcp can resolve the server. The probe script uses uv run --with rcsb-mcp.
• No API key. The RCSB APIs are public and unauthenticated. Read-only. Be considerate with request volume.

Install

This is a skill — it is documentation plus one script, so "installing" it means dropping the directory where your agent reads skills from, and registering the server with your MCP client.

Register the server (Hermes):

# ~/.hermes/config.yaml
mcp_servers:
  rcsb:
    command: uvx
    args: [rcsb-mcp]

Tools then register as mcp__rcsb__<tool_name>. A running session keeps its old tool list — open a new one, or /reload-mcp.

If your client launches with a filtered PATH (Hermes's gateway inherits only PATH, HOME, USER, LANG, TERM, SHELL, TMPDIR, XDG_*), pass uvx as an absolute path. A bare uvx fails silently there.

Any other MCP client (Claude Desktop, Cursor, MCP Inspector):

{ "mcpServers": { "rcsb": { "command": "uvx", "args": ["rcsb-mcp"] } } }

A remote endpoint also exists (https://mcp-beta.rcsb.org/mcp) if you would rather not run it locally.

Quick start — ask the server instead of guessing

uv run --no-project --with rcsb-mcp python scripts/rcsb_probe.py --list
uv run --no-project --with rcsb-mcp python scripts/rcsb_probe.py --schema rcsb_seqcoord_alignments
uv run --no-project --with rcsb-mcp python scripts/rcsb_probe.py rcsb_get_entries '{"entry_ids":["4B3F"]}' --pretty

--list and --schema read the server's own tools/list output, so they can never be stale. The third form runs a real tools/call. Add 2>/dev/null for clean JSON — the server logs to stderr.

Three real runs are committed under examples/ — tools_list.txt, get_entries_4B3F.json, and seqcoord_4B3F_1_to_uniprot.json. They were produced by the script, not written by hand.

The one mental model that matters

Search returns only identifiers. Data returns the metadata.

rcsb_query_*  /  rcsb_find_*   →  build a query (or resolve free text to an ontology id)
        ↓
rcsb_search_request            →  RUN it; ids + total_count + facets + an editor link
        ↓
rcsb_get_*                     →  batch those ids into ONE call for titles, organisms, resolution…

total_count is on every search response, so "how many…" never needs paging. The query builders do no IO.

What's in the skill

• The full 36-tool map, grouped by layer (Search 10 / resolvers 5 / Data 17 / SeqCoords 3 / report 1), with each tool's key argument names and, for the five resolvers, the exact attribute path to search with afterwards.
• Five recipes: find every structure of a protein (all three discovery routes, and why one of them is mandatory), construct-boundary and coverage checks, quality filtering via the composer, counting and facets, and report building.
• The verified argument shapes — the envelope, comp_ids, from_ref+to_ref, the report's required heading, why a polymer entity's default fields omit the sequence, and more. Each one cost a failed call.
• The beta gaps, so you do not build on a tool that returns nothing.
• A regression baseline (IGHMBP2 / P38935, seven probes with expected values) to re-run after any server upgrade — the cheapest test that the data path is still honest.

Pitfalls that will bite you

• Don't conclude "this protein has N structures" from one keyword search — alias/legacy names hide entries.
• Don't hand-write a digest, and don't pass an inner query where the envelope belongs.
• Don't trust the README's tool or parameter names. The schemas are the contract.
• Don't report a search hit as if metadata came with it — search returns ids only, so fetch before asserting a resolution, a title, or a citation.
• Don't page to get a count. total_count is right there.

Repository layout

rcsb-mcp-skill/
├── SKILL.md                        the rules — tool map, recipes, gotchas, baseline
├── README.md                       this file: install, usage, the pitfalls that bite
├── LICENSE
├── .gitignore
├── scripts/
│   └── rcsb_probe.py               one-shot MCP caller: --list / --schema / tools/call
└── examples/                       real, committed script output
    ├── tools_list.txt
    ├── get_entries_4B3F.json
    └── seqcoord_4B3F_1_to_uniprot.json

SKILL.md is the single source of truth for the rules; this README covers install, usage, and orientation, so the two don't drift into contradicting each other.

Credits

The server is by RCSB PDB — beta since 2026-10-14, MIT, at rcsb/rcsb-mcp. This repository only documents how to drive it. Bugs in the server belong upstream at rcsb/rcsb-mcp/issues; the maintainers ask for the question, the client, and the model used.

License

MIT — see LICENSE.