Developers · AI agents · research infrastructure

Pocket Science developer and agent documentation

Stable, same-origin routes for discovering Pocket Science, retrieving public evidence and negotiating the read-only MCP endpoint without guessing.

OpenAPI 3.1 AI Catalog

Authentication and safety

The canonical public-information API and MCP endpoint require no authentication. They are read-only and safe to call without invoking external actions. The website contact form is different: it is same-origin, rate-limited and protected by human reCAPTCHA. Agents may prepare an enquiry but must not submit it or contact anyone without explicit user approval.

Stable endpoints

Endpoint	Purpose	Authentication and limits
`GET /api/pocket-science.json`	Canonical typed services, projects, evidence, budget, consortium and contact data.	None. Stable public file; cache and avoid repeated fetches.
`POST /mcp/`	Stateless MCP initialization, capability listing and read-only tools.	None. Send one JSON-RPC 2.0 object per request.
`GET /openapi.json`	Typed OpenAPI 3.1 contract and reusable RFC 9457 error model.	None. Cache with revalidation.
`GET /.well-known/ai-catalog.json`	Bounded same-origin discovery catalog.	None.
`POST /api/contact.php`	Human project-enquiry form.	Same-origin, rate-limited and reCAPTCHA protected. Not an autonomous agent action.

No fixed public request quota is published for the read-only information and MCP endpoints. Clients should cache stable resources, identify automated traffic, avoid bursts and respect Retry-After whenever it is returned.

OpenAPI example

curl -H 'Accept: application/json' \
  https://pocket.science/api/pocket-science.json

The stable operation ID is getPocketScienceInformation. The response schema is PocketScienceInformation; failures use the reusable Problem schema.

MCP discovery without invoking tools

The endpoint supports MCP protocol versions 2024-11-05, 2025-03-26 and 2025-06-18. It is stateless: no session ID is required. Initialization and tools/list only negotiate and inspect capabilities; they do not call a tool.

curl -X POST https://pocket.science/mcp/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example","version":"1.0"}}}'

curl -X POST https://pocket.science/mcp/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Error models

Unknown /api/ routes and API failures return application/problem+json with RFC 9457 fields type, title, status, detail and instance, plus a stable code. MCP failures use standard JSON-RPC codes: -32700, -32600, -32601 and -32602.

iSPEX technical documentation

Pocket Science preserves the public iSPEX2 OSF project locally. These source documents are attributed to PML under CC BY-NC-ND 4.0 and are provided for inspection and reproducibility; the originals are not rewritten here.

Black Hole Finder technical evidence

Black Hole Finder demonstrates a production citizen-science observatory with web, iOS and Android participation, classification workflows, accounts, candidate imagery, researcher administration, community support, machine-learning assistance and telescope follow-up. Its public pages document capability and outcomes; they are not a public write API for classifications.