MCP server¶

linXiv-web can serve linXiv's own MCP tools over HTTP, so an AI agent such as Claude Code, Codex or OpenCode can search and work on your library. It is off by default.

Upstream linXiv ships linxiv-mcp as a local stdio server for the desktop app (see the linXiv README). linXiv-web builds the same binary and bridges it to MCP Streamable HTTP at /mcp, with a bearer token and a choice of which tools the agent gets.

How it works¶

flowchart LR
  client[MCP client] -- "HTTP /mcp" --> api[FastAPI]
  api -- stdio --> mcpsrv[linxiv-mcp]
  mcpsrv --> data[("papers.db + pdfs/")]

• Each MCP session (one initialize) gets its own linxiv-mcp process. At most 4 sessions run at once; a session closes after 30 minutes idle, and a restart of the container drops all sessions (clients re-initialize).
• Requests in one session run one at a time. Replies are plain JSON; GET /mcp answers 405 (no server-sent events).
• Which tools a client sees and may call is decided by the bridge (server/app/mcp_bridge.py), not by linxiv-mcp.

Turning it on¶

1. Open Settings → Integrations.
2. Tick Serve linXiv's MCP tools at /mcp and pick the tools the agent gets (see Profiles). Save.
3. Click Create token. The token is shown once; only its SHA-256 is stored. Replace token or Revoke token disconnects every open session.

The card then shows the connect commands below with your server URL and token filled in.

Connecting a client¶

Use your server's address in place of http://127.0.0.1:8086, for example the HTTPS name behind your reverse proxy.

Claude Code¶

claude mcp add --transport http linxiv http://127.0.0.1:8086/mcp --header "Authorization: Bearer <token>"

Add --scope local (this project only, the default), --scope user (every project) or --scope project (writes .mcp.json into the repository, so keep the token out of git). Check with claude mcp list; the tools appear as mcp__linxiv__* after a restart or /mcp reconnect.

Codex¶

Codex reads the token from an environment variable, which must be set in the shell that starts Codex:

export LINXIV_MCP_TOKEN=<token>
codex mcp add linxiv --url http://127.0.0.1:8086/mcp --bearer-token-env-var LINXIV_MCP_TOKEN

or in ~/.codex/config.toml:

[mcp_servers.linxiv]
url = "http://127.0.0.1:8086/mcp"
bearer_token_env_var = "LINXIV_MCP_TOKEN"

OpenCode¶

Add a remote server to opencode.json (per project) or to your global OpenCode config. {env:LINXIV_MCP_TOKEN} reads the token from the environment, so set it as for Codex:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "linxiv": {
      "type": "remote",
      "url": "http://127.0.0.1:8086/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:LINXIV_MCP_TOKEN}" }
    }
  }
}

Profiles¶

Never exposed, in any profile:

• get_settings, update_setting: the settings store holds API keys.
• backup_database, restore_database, import_pdf, import_bibtex, import_zotero, import_project, export_project, export_project_bibtex, export_project_obsidian, export_project_zotero, set_full_text: they read or write file paths on the server. Use the web UI for these.

download_pdf with a caller-chosen url is refused; the paper's stored link is used, so the agent cannot make the server fetch an arbitrary host.

Tools added in a new upstream release stay hidden until they are classified in mcp_bridge.py (a test against the real binary fails on any unclassified tool).

Permission hints¶

linxiv-mcp sets no MCP tool annotations, so the bridge adds them to every tool in tools/list, derived from the tool's profile tier. Clients use them to decide when to ask before a call.

Hints are advice to the client, not access control: the profile decides what can be called. A reasonable client setup is to auto-allow read-only tools and always confirm destructive ones by hand.

Tool reference¶

Descriptions come from linxiv-mcp (linXiv v0.7.0). Hints: read-only, edit (undoable), destructive (permanent), idempotent, open world (calls outside services).

Read only (32 tools)¶

Read + edit library (36 more)¶

Full (7 more)¶

Security¶

• /mcp does not use the browser login or CSRF token. It needs Authorization: Bearer <token>; a missing or wrong token gets 401.
• While the switch is off, /mcp answers 404.
• A request carrying another site's Origin header is refused with 403, which blocks DNS-rebinding attacks from a browser.
• Behind a reverse proxy, pass the Host header through (see self-hosting.md) so the Origin check compares against the public name.
• Pick the smallest profile that does the job. Full lets an agent delete papers and projects permanently.

Troubleshooting¶

Probe the endpoint by hand. Streamable HTTP needs the Mcp-Session-Id returned by initialize on every later request:

URL=http://127.0.0.1:8086/mcp
AUTH="Authorization: Bearer $LINXIV_MCP_TOKEN"
ACCEPT="Accept: application/json, text/event-stream"
CT="Content-Type: application/json"

SID=$(curl -s -D - -o /dev/null -X POST "$URL" -H "$AUTH" -H "$ACCEPT" -H "$CT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
  | tr -d '\r' | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}')

curl -s -X POST "$URL" -H "$AUTH" -H "$ACCEPT" -H "$CT" -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -s -X POST "$URL" -H "$AUTH" -H "$ACCEPT" -H "$CT" -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | jq -r '.result.tools[] | "\(.name)\t\(.annotations.readOnlyHint)\t\(.annotations.destructiveHint)"'

The current session count shows on the Settings card.