Docs / MCP
Model Context Protocol
Endpoint https://pubphys.com/mcp (Streamable HTTP). Reading needs no sign-in and no key. In Claude, add
it as a custom connector with this address and no authentication. An AI agent can also prepare private drafts for a
member who gives it an agent key;
nothing is published until the member signs it on the site.
The server is stateless: each request is one JSON-RPC message sent with POST and answered with one
JSON object; it issues no session and offers no event stream. Clients that only speak the older HTTP+SSE
transport can still use https://pubphys.com/mcp/sse (messages at /mcp/messages), which
serves the same reading tools; the tools that need an agent key answer only at /mcp. Requests are limited to
120 a minute per address, a batch to 20 messages and a request
to 256 kB.
curl -s https://pubphys.com/mcp -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_fields","arguments":{}}}'
Tools
list_fields: fields with topic and problem counts.list_topics(field,sort): the topics of a field.search_problems(query,field,topic,limit,sort): matching problems.top_problems(field,count): the problems in order of importance, as the home page lists them, for all physics or one field (up to 100; until ranked lists are enabled, in slug order).get_problem(slug): one problem in full.get_submission_guide(kind): what PubPhys accepts, field by field, with the limits and the writing rules.
sort is slug (the default) or top, the order of importance
as in the API
(how ranking works).
Contributing with an agent key
A member with an ORCID iD creates an agent key on the account page
and gives it to an AI agent. The agent sends it to /mcp as
Authorization: Bearer <key>. The key does one thing: it prepares private drafts on that member's
account. It opens no page of the site and signs, stages and publishes nothing. The member opens the url the agent
returns, reads the draft in its usual form, changes it if needed and signs it with ORCID; until then nothing about
the draft is public, and the member can delete it.
draft(kind,agentand the fields of the kind): a solution, disproof or idea on a problem; a new problem under a topic of a field; a subproblem of a problem; a new topic in a field; or a correction of a problem the member may change. A new problem opens the member's Propose a problem page with its text; the member's Upload logs that text, and the member then checks the fields and signs.agentnames the AI system, lowercase, such asvendor:model-1; the draft page shows it as "AI system, as declared by the agent", and the signed record lists it among the AI systems that helped.find_similar(problem, ortitleandprecise): the public results on a problem, with the record hashesbuilds_oncites, or the most similar public problems.list_my_drafts: the open drafts this key prepared, without their text.
An agent never overwrites a draft: one form holds one open draft, the member's or an agent's, and the draft, once
written, is changed or deleted only by the member. Limits: 3 keys per account;
300 tool calls an hour per key; 40 draft calls a day
per account, refused ones included; 20 open drafts prepared by agents per account. A wrong,
revoked or unusable key gets one answer, Unauthorized, and a key revoked while its call runs writes nothing. The member revokes a key on the account page; a suspension, a
password change or reset, unlinking the ORCID iD and "This was not me" revoke every key of the account.
Resources
pubphys/fieldsandpubphys/stats.