> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperzilla.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Paperzilla with MCP

> Connect your MCP client to Paperzilla and access projects, feed search, paper detail, and markdown in natural language.

export const AiAgents = ({path}) => <Tip>
    <b>AI agents</b>: This page is available as <a href={path + '.md'}>markdown</a>. See also the <a href="/llms.txt">docs index</a> and <a href="/llms-full.txt">full docs</a>.
  </Tip>;

<AiAgents path="/guides/mcp" />

Use Paperzilla MCP when you want your AI assistant to pull your Paperzilla data directly.

If you are using Claude's custom connector flow, start with [Use Paperzilla MCP with Claude](/guides/claude). Claude uses a client-specific setup flow.

If you are using Codex, start with [Use Paperzilla with Codex](/guides/codex). Codex uses its own MCP config flow and also supports a separate CLI-based path.

Endpoint:

`https://paperzilla.ai/api/mcp`

If you want the short explanation of how MCP clients discover this URL and then learn what tools exist, see [How do clients discover the Paperzilla MCP URL and tools?](/answers/how-do-clients-discover-paperzilla-mcp).

## What you can do

* List your projects
* Open one project
* Pull feed items with filters like Must Read, since date, and limit
* Search across a full project feed by title, author, abstract, or summary text
* Open one canonical paper by paper ID, or one project recommendation by recommendation ID
* Get markdown for one paper or recommendation, and queue markdown generation when project context allows it
* Get the project's Atom URL

## Quickstart

### 1. Create your MCP API key

Create a personal MCP key in your Paperzilla dashboard:

1. Open your [dashboard](https://paperzilla.ai/dashboard).
2. Click **MCP API key** (top-right, key icon).
3. Click **Generate key**.
4. Copy the key and store it securely.

You can also use the same **MCP API key** panel to revoke the key.

If your account does not show that button yet, use the API key endpoints in the [developer appendix](/api-reference/mcp).

Keep this key private. You only see the plaintext value when you create or rotate it.

### 2. Add Paperzilla to your MCP client

Use:

* URL: `https://paperzilla.ai/api/mcp`
* Auth: either `Authorization: Bearer <your-mcp-api-key>` or `https://paperzilla.ai/api/mcp/?key=<your-mcp-api-key>`

Header-based example config shape:

```json theme={null}
{
  "mcpServers": {
    "paperzilla": {
      "transport": {
        "type": "streamable_http",
        "url": "https://paperzilla.ai/api/mcp"
      },
      "headers": {
        "Authorization": "Bearer pzmcp_..."
      }
    }
  }
}
```

URL-only client example:

```text theme={null}
https://paperzilla.ai/api/mcp/?key=pzmcp_...
```

### 3. Ask your assistant to call Paperzilla

Try requests like:

* "List my Paperzilla projects."
* "Show must-read papers for project `<project-id>` since `2026-02-01` limit 20."
* "Search project `<project-id>` for papers about proximity graphs."
* "Open paper `<paper-id>`."
* "Open recommendation `<project-paper-id>`."
* "Get the markdown for paper `<paper-id>` or recommendation `<project-paper-id>`."
* "Get the Atom URL for project `<project-id>`."

## Available tools today

| Name                                  | Purpose                                                                      | CLI parity                                                                   |
| ------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `projects_list`                       | List your projects                                                           | `pz project list --json`                                                     |
| `projects_get`                        | Get one project                                                              | `pz project <id> --json`                                                     |
| `feed_get`                            | Get project feed with filters                                                | `pz feed <id> --must-read --since --limit`                                   |
| `feed_search`                         | Search the full project feed with text query plus optional filters           | `pz feed search --project-id <id> --query <q>`                               |
| `feed_atom_url`                       | Get Atom URL for a project                                                   | `pz feed <id> --atom`                                                        |
| `paper_get`                           | Get one paper by paper ID or one recommendation by recommendation ID         | `pz paper <paper-ref>` or `pz rec <project-paper-ref>`                       |
| `paper_markdown`                      | Get paper markdown or queue markdown generation                              | `pz paper <paper-ref> --markdown` or `pz rec <project-paper-ref> --markdown` |
| `feed_title_filter` (optional prompt) | Ask the model to call `feed_search` for a server-side full-feed title search | No direct CLI equivalent                                                     |

Legacy dotted names like `paper.get` still work for direct `tools/call` compatibility, but Claude-compatible clients should use the underscore names above.

## How feed search works

Use `feed_search` when you want your MCP client to search across the whole project feed, not just currently visible items.

`feed_search` supports:

* `project_id`
* `q`
* `feedback_filter`
* `must_read`
* `limit`
* `offset`

It returns:

* `items`
* `limit`
* `offset`
* `has_more`
* `query`

Notes:

* search is server-side and scans the full feed
* query terms use prefix matching, so `Proxi` matches `Proximity`
* search is rank-first and does not return an exact total count in v1

If you want a focused Q\&A version, see [Can Paperzilla MCP search across an entire project feed?](/answers/can-paperzilla-mcp-search-across-an-entire-project-feed) and [How do I search a project feed through Paperzilla MCP?](/answers/how-do-i-search-a-project-feed-through-paperzilla-mcp).

## About prompts

You can ignore prompts and use direct tool calls only.

If your client supports prompts, `feed_title_filter` helps with one task:

* Call `feed_search`
* Search the full feed server-side for a title keyword
* Return matching results and explain that the search covers the full feed

## Markdown results

`paper_markdown` always returns a structured result.

* `status: "ready"` means markdown content is included in the response
* `status: "queued"` means Paperzilla accepted the request and queued markdown generation
* `status: "unavailable"` means that paper does not currently have a usable markdown source

## CLI vs MCP

Use [CLI](/guides/cli) for shell scripts and deterministic command outputs.

Use MCP when your assistant should reason across tools and ask follow-up questions.

Use [RSS/Atom](/guides/feeds) for passive feed-reader polling.

## Key safety

* Treat your MCP key like a password
* Rotate it immediately if exposed
* Revoke it from **MCP API key** in the dashboard if you stop using MCP

## Troubleshooting

* `401 Unauthorized` on `/api/mcp`: missing, revoked, or invalid MCP API key
* Empty or unexpected results: confirm you are using the key for the correct Paperzilla account
* `404 Not Found` for project/feed/paper calls: the resource is not accessible in your account
* `isError: true` with an ambiguous short ID message: retry with the full UUID instead of the 8-character short ID