# PapersFlow Developer Resources

PapersFlow exposes its research tools to AI agents through a hosted Model Context Protocol (MCP) server. Use it when an agent needs scholarly search, citation verification, citation-graph exploration, a user's private PapersFlow library, or a permissioned DeepScan research workflow.

## Quick start

- MCP endpoint: `https://doxa.papersflow.ai/mcp`
- Transport: Streamable HTTP
- Current protocol: `2025-11-25` (headerless compatibility fallback: `2025-03-26`)
- OpenAPI description: [PapersFlow MCP OpenAPI](https://papersflow.ai/openapi.json)
- MCP Registry manifest: [PapersFlow MCP server.json](https://papersflow.ai/mcp/server.json)
- API catalog: [PapersFlow API catalog](https://papersflow.ai/.well-known/api-catalog)

Most MCP clients can discover PapersFlow OAuth automatically from the protected-resource metadata. An authenticated PapersFlow account can also create a personal access token in **Settings → Integrations → MCP**. The Free plan is available without a payment card; paid plan entitlement is checked separately for paid research runs.

## Authentication and least-privilege scopes

Every MCP JSON-RPC POST requires either an OAuth access token or a PapersFlow MCP personal access token. OAuth uses the authorization-code flow with PKCE S256 and supports dynamic client registration. Request only the scopes needed for the tools the agent will call.

| Scope | Use it for |
| --- | --- |
| `mcp.public.read` | Public paper search, citation verification, related-paper discovery, and citation graphs |
| `mcp.library.read` | Reading the signed-in user's library, collections, papers, and connected-source results |
| `mcp.library.write` | Creating or updating collections, saving or removing papers, and starting or cancelling integration sync |
| `mcp.research.read` | Reading DeepScan status, live snapshots, reports, and evidence summaries |
| `mcp.research.run` | Starting DeepScan; a paid-plan entitlement and available usage are also required |

Discovery endpoints:

- Protected resource: `https://doxa.papersflow.ai/.well-known/oauth-protected-resource/mcp`
- Authorization server: `https://doxa.papersflow.ai/.well-known/oauth-authorization-server`
- OpenID configuration: `https://doxa.papersflow.ai/.well-known/openid-configuration`
- Dynamic client registration: `https://doxa.papersflow.ai/oauth/register`

Dynamic registration returns a server-owned `client_id`, `registration_client_uri`, and `registration_access_token`. Store the registration access token as a credential and send it as a Bearer token only to that registration URI. The URI supports RFC 7592 `GET`, `PUT`, and `DELETE`; `PUT` rotates the registration access token and any confidential-client secret, while `DELETE` revokes the registration. Registration responses use `Cache-Control: no-store`.

## Call PapersFlow MCP

MCP clients should send `Accept: application/json, text/event-stream` on POST requests. A direct initialization request looks like this:

```bash
curl https://doxa.papersflow.ai/mcp \
  --request POST \
  --header "Authorization: Bearer $PAPERSFLOW_MCP_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"your-agent","version":"1.0.0"}}}'
```

After initialization, call `tools/list` to receive the tools allowed by the token's scopes. Public research tools include `search`, `fetch`, `verify_citation`, `search_literature`, `find_related_papers`, `get_citation_graph`, `get_paper_neighbors`, and `expand_citation_graph`. Authenticated library and research tools appear only when their required scope is present.

The JSON-RPC POST is stateless and returns JSON (or an empty `202` for notifications); it does not issue `Mcp-Session-Id` or produce an SSE response. A conforming `GET /mcp` probe with `Accept: text/event-stream` returns `405 Method Not Allowed`, as does `DELETE /mcp`, because there is no transport session to stream or delete.

## Errors and support

- `401` means the bearer token is missing or invalid; follow the `WWW-Authenticate` resource-metadata link.
- `403` means the token lacks the required scope; request the scope named in the challenge instead of broadening every permission.
- A tool result with `isError: true` can report product errors such as `UPGRADE_REQUIRED` or `LIMIT_REACHED` without turning the JSON-RPC response into a transport failure.
- Support: [PapersFlow contact](https://papersflow.ai/contact) or `developer@papersflow.ai`.

See [llms.txt](https://papersflow.ai/llms.txt) for agent-oriented product guidance and [sitemap.xml](https://papersflow.ai/sitemap.xml) for the complete public content index.