# CiteTrue MCP Server

Add academic-citation verification to Claude Desktop, Cursor, or any MCP-compatible client. Tools wrap the CiteTrue REST API — same credits, same accuracy, launched locally over stdio.

**Package:** [`@citetrue/mcp-server`](https://www.npmjs.com/package/@citetrue/mcp-server) (npm) · `npx -y @citetrue/mcp-server`
**Source:** `mcp/` in the CiteTrue repo.

## What you get

| Tool           | Purpose                                                                                | Credits / call               |
| -------------- | -------------------------------------------------------------------------------------- | ---------------------------- |
| `verify`       | Split a text blob into references and verify each. `depth` selects accuracy vs. cost.  | 1 or 5 per ref by depth      |
| `get_credits`  | Account credit balance.                                                                | 0                            |

## Quickstart

1. **Get an API key.** Go to [Dashboard → API Keys](https://citetrue.com/dashboard/api), click **New API Key**, copy the `sk_…` string. Shown once.

2. **Add the server to your MCP client config.**

   **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

   ```jsonc
   {
     "mcpServers": {
       "citetrue": {
         "command": "npx",
         "args": ["-y", "@citetrue/mcp-server"],
         "env": {
           "CITETRUE_API_KEY": "sk_..."
         }
       }
     }
   }
   ```

   **Cursor** — Settings → MCP → *Add new MCP server*. Same `command` / `args` / `env` shape.

   **Windsurf / Zed / any stdio MCP client** — whatever their config path is, use the same three fields.

3. **Restart the client.** Verify the server appears in the MCP tools list — e.g. in Claude Desktop, look for the hammer icon on the composer; you should see `verify`, `get_credits`.

4. **Try it.** Ask the assistant something like *"Verify these citations: [paste references]"*. It will call `verify` (depth 1 by default) and summarize the results.

## Configuration

| Env var             | Default                      | Notes                              |
| ------------------- | ---------------------------- | ---------------------------------- |
| `CITETRUE_API_KEY`  | — (required)                 | `sk_…` bearer token.               |
| `CITETRUE_API_URL`  | `https://api.citetrue.com`   | Override for self-hosted deploys.  |

## Tools

### `verify`

Split a free-form text blob into individual references and verify each. `depth` selects accuracy vs. cost.

**Parameters** — supply exactly one of `text`, `refHash`, or `taskHash`:
- `text` (string) — raw text containing one or more references. Accepts numbered lists, bullets, blank-line-separated, BibTeX, or in-text prose with author-year citations (when `depth >= 5`). Max 10MB.
- `refHash` (string) — upgrade a single prior reference to a deeper run. Requires `depth >= 5` and `parentTaskHash`.
- `parentTaskHash` (string) — required when using `refHash`; the task that originally produced the ref.
- `taskHash` (string) — resume a previously-started task; replays cached state. No re-billing.
- `depth` (1 | 5, optional, default `1`) —
  - `1` — fast: handles structured reference lists and inline prose. 1 credit per reference.
  - `5` — deep: AI-driven verification; handles unusual formats and gives a stronger verdict. Each reference first gets a fast pass; if that already finds it authentic, it's billed just 1 credit and deep verification is skipped — otherwise 5.
  - `20` exists as a closed-beta tier and is not enabled for public use.
- `force` (bool, optional) — bypass cached results (forces a fresh run, charges full cost).

**Returns**
```jsonc
{
  "taskHash": "...",
  "refs": [
    {
      "hash": "a1b2c3...",
      "text": "[1] Vaswani, A., Shazeer, N., Parmar (2017)...",
      "assessment": "authentic",       // authentic | inauthentic | unsure | invalid | error | exceeded
      "value": {
        "type": "citation",            // standard | citation | pdf | html | book
        "title": "Attention is all you need",
        "authors": ["A Vaswani", "N Shazeer", "N Parmar"],
        "year": 2017,
        "url": "https://..."
      },
      "note": "",                      // free-form one-line natural-language explanation (English); empty on clean matches
      "notices": [],                   // see notice values below
      "confidence": 0.97,              // x5 unsure only
      "data": {
        "depth": 1,                    // highest depth that has run (1 or 5); derive deepVerified locally as depth >= 5
        "cost": 1
      }
    }
  ],
  "cost": 2,
  "balance": 248
}
```

`note` is free-form natural-language (English) intended for end-user display; for programmatic checks, match on `notices[]` instead.

**Assessment values**

- `authentic` — paper exists and is the one cited; `value` contains the matched paper.
- `unsure` — found something but can't confirm; `notices` and `confidence` describe why.
- `inauthentic` — definitively not found / fabricated / unrelated.
- `invalid` — input wasn't a citation; pipeline refused to search.
- `error` — verification failed on this ref; `data.errors[]` lists tokens.
- `exceeded` — credits ran out before this ref ran.

### `get_credits`

Returns the account's credit balance. Useful for pre-flight checks before a big verify call.

## Notice values

`notices[]` on a ref is a set of soft-fail flags — they enrich a match independent of `assessment`. An `authentic` result can still carry notices worth showing.

| Value               | Meaning                                                       |
| ------------------- | ------------------------------------------------------------- |
| `likely`            | Only one candidate, match uncertain.                          |
| `year`              | Year in the citation doesn't match the matched source.        |
| `authors`           | Author list mismatch.                                         |
| `title`             | Title differs between the citation and the matched source.    |
| `link`              | Citation has no URL / DOI to cross-check against.             |
| `url_inaccessible`  | Cited URL couldn't be fetched.                                |
| `url_inconsistent`  | URL resolves but content doesn't match the citation metadata. |
| `url_mismatch`      | URL points to a different paper.                              |
| `url_unsure`        | URL parse was ambiguous.                                      |
| `url_incorrect`     | URL has malformed syntax.                                     |
| `doi_incorrect`     | DOI is malformed or doesn't resolve.                          |

## Billing

Tools consume credits from the account that owns the API key. Same rates as the REST API:
- `verify`: 1 credit/ref at `depth=1`. At `depth=5`, each reference first gets a fast pass — if it already finds the reference authentic, billed 1 (deep skipped), otherwise 5. `refHash` upgrades always run the full deep verification (5).
- `get_credits`: free.

If credits run out mid-call, remaining refs return with `assessment: "exceeded"`. Buy more at [citetrue.com/pricing](https://citetrue.com/pricing).

## Troubleshooting

**"CITETRUE_API_KEY is not set" on startup.** The `env` block in the MCP client config didn't reach the subprocess. Most clients require restarting the whole app (not just reloading the chat) after editing the config file.

**Tools don't appear in the client.** Check the MCP client's log — on Claude Desktop: `~/Library/Logs/Claude/mcp*.log`. A missing `npx` on the shell `PATH` is the most common cause; either install Node globally or point `command` at the absolute `node` binary with `args: ["/path/to/@citetrue/mcp-server/dist/index.js"]`.

**429 errors under heavy use.** API key rate limit is 10 burst / 60 sustained per minute. Rare for interactive LLM use; if you hit it, batch references into fewer `verify` calls rather than looping.

**Stale results.** Same-text verify calls are cached. Set `force: true` (exposed as a tool argument) to bypass.

## See also

- [REST API reference](https://citetrue.com/docs/api) — raw HTTP endpoints, SSE events, error codes.
- [API reference (LLM-friendly)](https://citetrue.com/docs/api.md) — the same in plain markdown.
- [Guides](https://citetrue.com/docs/guides) — user-facing how-tos.
- [MCP spec](https://modelcontextprotocol.io) — the protocol itself.