mcp_server/README.md

pwc MCP server

Anonymous, read-only Model Context Protocol access to the public Papers With Code catalog.

The server uses stock-client MCP 2025-11-25 over Streamable HTTP and also serves experimental 2026-07-28 discovery on the same /mcp endpoint. It returns versioned structured output with compact Markdown fallbacks.

Run locally

uv run --project mcp_server pwc-mcp

The default listener is 127.0.0.1:7860. Set PWC_MCP_HOST, PORT, or PWC_API_URL to override the bind address, HTTP port, or compatible PwC API.

curl http://127.0.0.1:7860/health

Tools

Every read-only pwc CLI research command is one tool, and every research flag of that command is a tool parameter, so results match pwc ... --json. Each result carries schema_version and data, the complete CLI JSON payload, next to typed projections such as items or evaluations.

Tool	CLI command
search_papers	pwc search
get_paper_info	pwc paper info
get_paper_evaluations	pwc paper evaluations
read_paper	pwc paper read (64 KiB chunks with a continuation cursor)
list_papers	pwc paper list
list_recent_papers	pwc paper recent
list_trending_papers	pwc paper trending
get_related_papers	pwc paper related
get_paper_lineage	pwc paper lineage list
get_task	pwc task --name
list_tasks	pwc task list
get_method	pwc method --name
list_methods	pwc method list
get_conference	pwc conference --name
list_conferences	pwc conference list
get_organization	pwc organization --name
list_organizations	pwc organization list
get_framework	pwc framework --name
list_frameworks	pwc framework list
get_benchmark	pwc benchmark --name
list_benchmarks	pwc benchmark list

Parameter names follow the CLI flags except for the established MCP names published_after/published_before (--start-date/--end-date), limit (--page-size), authors (--author), order_direction (--order-dir), minimum_evaluations (--min-eval-count), and include_evaluations (--include-evals). Terminal-only flags (--json, --implementation-coverage, --flat) have no parameter because MCP output is always structured. Hosted differences from the CLI: limit is capped at 25, get_paper_info returns compact official-first resources, and read_paper is chunked. search_papers defaults to hybrid mode like pwc search. tests/test_parity.py fails when the CLI parser and the tool schemas drift.

All tools are annotated read-only and idempotent. Search is deterministic; the caller controls hybrid (default), keyword, or semantic mode. read_paper fetches at most one 64 KiB catalog chunk per call and returns a signed, one-hour continuation cursor when more Markdown remains. Continuations stay pinned to the resolved paper and content version, so a changed paper fails with an explicit restart response; any reference that resolves to the same paper (the numeric catalog ID after starting from the arXiv ID, say) may carry the cursor. A placeholder cursor such as "next" with nothing saved reads from the beginning.

Paper tools fall back to the public API's public-metadata endpoint for papers the catalog does not hold: get_paper_info and read_paper return Hugging Face Papers, arXiv, or Crossref (DOI) metadata and the abstract with in_catalog: false, a note, and labelled available_at links to cite instead of a Papers With Code page; get_related_papers returns a catalog search for the public title with the same note and links. A reference the endpoint maps to a catalog paper returns the catalog paper. Titles go to the sibling public-metadata/search endpoint, which accepts only an exact arXiv or Crossref title match, or the single arXiv paper sharing the "Name:" before its colon. get_benchmark answers a metric the leaderboard does not report with the unfiltered leaderboard and a metric_note naming the available metrics.

Resources

• pwc://papers/{paper}
• pwc://papers/{paper}/markdown
• pwc://tasks/{task}
• pwc://benchmarks/{benchmark}

Configuration

Variable	Purpose
PWC_API_URL	Compatible catalog API; defaults to production PwC
PWC_MCP_HOST	Listener address; defaults to loopback (127.0.0.1)
PWC_MCP_ALLOWED_HOSTS	Comma-separated HTTP Host allowlist
PWC_MCP_ALLOWED_ORIGINS	Comma-separated browser Origin allowlist
PWC_MCP_CURSOR_KEY_CURRENT	Required secret used to sign continuation cursors
PWC_MCP_CURSOR_KEY_PREVIOUS	Optional previous secret accepted during key rotation
PORT	HTTP port; defaults to 7860
PWC_MCP_REQUEST_LIMIT	Requests per client per minute; defaults to 60
PWC_MCP_SEMANTIC_LIMIT	Semantic or hybrid searches per client per minute; defaults to 10
PWC_MCP_CONCURRENCY_LIMIT	Concurrent requests per client; defaults to 4
PWC_MCP_GLOBAL_CONCURRENCY_LIMIT	Concurrent requests across all clients; defaults to 128 and sizes the tool thread pool
PWC_MCP_TRUSTED_PROXY_CIDRS	Comma-separated networks of a non-loopback reverse proxy whose X-Forwarded-For is trusted; empty by default
LOG_LEVEL	Content-free operational log level

Native clients may omit Origin. Browser requests must match the configured allowlist. A first-party client on the same host may send X-PwC-MCP-Client: <token> to name its rate-limit identity (for example one hashed chat session); the header counts only on a direct loopback connection without X-Forwarded-For, so proxied public traffic cannot use it. The server does not log queries, paper references, request bodies, raw IP addresses, or authorization headers.

Behind a reverse proxy that does not run on the same host, such as the Hugging Face Spaces ingress, set PWC_MCP_TRUSTED_PROXY_CIDRS to the proxy's networks. A request whose direct peer falls in one of them is limited by the right-most X-Forwarded-For hop outside those networks; hops further left are client-supplied and ignored. Such requests can never name an identity with X-PwC-MCP-Client. Loopback peers keep the behaviour above. List only networks that hold nothing but the proxy: any peer inside them can choose its own rate-limit identity.

The hosted defaults allow 60 total requests and 10 semantic or hybrid searches per minute per client IP, with at most four concurrent requests per IP and 128 globally. Tool inputs cap list results at 25, catalog calls time out after 25 seconds, and request, upstream, and serialized MCP response bodies are bounded to 2 MiB. The global ceiling is 128 concurrent requests by default. Markdown chunks use a bounded 256-entry/16 MiB in-memory cache.

GET /.well-known/mcp exposes connection metadata and GET /docs publishes the live tool schema. A bare GET /mcp returns 405; protocol requests use POST /mcp. The server also exposes find_papers, compare_leaderboard, and survey_task prompts.

Test

uv run --project mcp_server pytest mcp_server/tests

The canonical hosted service is deployed as an immutable VPS component and published through https://paperswithcode.co/mcp. The huggingface/paperswithcode-mcp Docker Space remains an optional fallback; its container explicitly binds to 0.0.0.0.