Install and connect

For most people, Mdtero is connected by an Agent. You do not need to learn the CLI commands first.

Cloud MCP (ChatGPT / Claude / Cursor)

One address:

https://api.mdtero.com/mcp

Sign in with a Mdtero account over OAuth. Save an Elsevier key only at https://api.mdtero.com/mcp/settings. Do not paste the key into chat. Campus subscription full text still needs the Relay helper on a computer that can reach the publisher. Open access and some API routes do not. Cloud agents (ChatGPT, Claude.ai) leave the campus network, so Relay remains required for institutional access.

Client	How to add
ChatGPT	Plugins → + → Add custom MCP server, choose OAuth
Claude.ai / Claude Desktop	Customize → Connectors → Add custom connector, paste the URL
Cursor	Add "url": "https://api.mdtero.com/mcp" in mcp.json, then complete OAuth
Claude Code	claude mcp add --transport http mdtero https://api.mdtero.com/mcp, then /mcp to sign in

Codex and the ChatGPT desktop app can also install the same connection from GitHub:

codex plugin marketplace add JonbinC/doi2md

Restart the desktop app, choose the Mdtero marketplace, and install Mdtero Reader. That package only stores the public MCP address. It does not contain the parser, and it is not the OpenAI public directory listing.

Desktop agents can keep using local mdtero mcp serve (stdio) without cloud OAuth.

Connect an Agent

1. Open Mdtero Console and create a new API key.
2. Copy the setup prompt. The same prompt works in Cursor, Trae, WorkBuddy, Claude Code, Codex, and other supported agents.
3. Paste that prompt into the Agent you trust. It will read this guide, install the supported Mdtero client, and confirm when it is ready.

Or install the portable skill yourself first:

npx skills add JonbinC/doi2md
# or from the website discovery index:
npx skills add https://mdtero.com/agent-skills

Discovery index: https://mdtero.com/.well-known/agent-skills/index.json

The prompt contains a one-time-visible key. Treat it as a password: give it only to a trusted Agent, and do not paste it into a repository, terminal history, logs, or a second chat. Revoke the key in Console if you no longer trust that environment.

If you install it yourself

The supported alpha client is the Python mdtero package:

uv tool install --upgrade mdtero
mdtero setup

If uv is unavailable, use the installer instead:

curl -Ls https://mdtero.com/install.sh | sh

mdtero setup opens the secure sign-in flow. When working with a Console key, enter it only when the client asks securely; do not append it to a command. For the full command reference, see the API reference.

Choose your environment

Environment	Recommended path
Campus Windows/macOS with a browser	CLI. The installer prepares the local access helper automatically; the browser extension is only a fallback for current-tab/session capture.
Server only	CLI/API key. Use OA/API/HTTP routes or upload a file; there is no local browser entitlement.
Server plus a campus computer	CLI on the server + Relay on the campus computer. This is the recommended path for browser-authorized closed or bot-protected papers.
Server plus campus VPN	CLI/API key + VPN/proxy. This helps IP-authorized machine-readable sources but does not replace a browser session.

The third path keeps the Agent in the cloud while the user's own browser stays on the campus network. Relay sends only the requested, validated PDF or sanitized static article HTML to Mdtero; it never exports cookies, credentials, browser storage, or a general browser session. The Campus relay is managed by the CLI on supported desktop installs and remains optional on servers.

A server may also run a narrowly allowlisted headless worker for open-access publisher pages. That operator feature has no user cookies or institution login and is not a general FlareSolverr or closed-content path.

Browser extension and saved files

The CLI and its local access helper are the default path. Use the browser extension only when a paper is already open in your browser, or when a publisher depends on a browser session that the dedicated Mdtero Access profile cannot use. You can also upload a PDF, EPUB, HTML, or XML file that you are allowed to use.

Mdtero processes material you are permitted to access. It does not grant or bypass publisher subscriptions, institutional authorization, or paywalls.

Local access helper

On desktop installs, Mdtero prepares the local access helper automatically. When the computer is on a campus network, it can provide the campus HTTP outlet and, when enabled, a separate Mdtero Access browser for eligible publisher tasks. Server and headless installs skip the desktop browser component.

The helper is bound to your Mdtero account. Its local-browser mode can capture only approved article HTML or PDF for that same account; it never exports cookies, credentials, browser storage, or a general browser-proxy interface. You must complete any institutional sign-in or publisher challenge yourself, and the publisher must still authorize the content.

Advanced operating details are maintained with the component guide: Campus Relay guide.

Updating

Ask your Agent to update Mdtero using this guide, or rerun:

uv tool upgrade mdtero

The public workflow stays stable: submit permitted material, wait for the task, download structured Markdown, and retain citations in research conclusions.