API Keys and Configuration

PRIMA Scholar works with no settings at all. Nine of the ten databases need no key, and the library uses a default location when you set none. Six optional settings let you add the CORE database, identify yourself to two databases, use your own API keys and move the library file.

The Six Settings

Setting	Server	What It Does	Where to Get It
CORE_API_KEY	Search	Turns on the CORE database and CORE full-text retrieval. Without it, CORE is skipped	A free API key from CORE, on the CORE API services page at https://core.ac.uk/services/api
PUBMED_API_KEY	Search	Raises the built-in PubMed limit from 3 to 10 requests a second	An API key from your NCBI account settings, at https://www.ncbi.nlm.nih.gov/account/
SEMANTIC_SCHOLAR_KEY	Search	Sent to Semantic Scholar with each request. The built-in limit stays at 100 requests every 5 minutes	A Semantic Scholar API key, requested from the Semantic Scholar API page at https://www.semanticscholar.org/product/api
OPENALEX_MAILTO	Search	Sent to OpenAlex as the mailto contact address on each request, which places the requests in the OpenAlex polite pool. The built-in limit stays at 10 requests a second	Your own email address
CROSSREF_MAILTO	Search	Sent to CrossRef as a contact email in each request, for its polite pool. The built-in limit stays at 50 requests a second	Your own email address
RESEARCH_LIBRARY_PATH	Library	Sets where the library database file lives	A file path of your choice. The default is ~/.research-library/library.db

When OPENALEX_MAILTO is unset or empty, the search server uses the CROSSREF_MAILTO address for OpenAlex as well. You can therefore set one email address and have it reach both services.

An empty or blank RESEARCH_LIBRARY_PATH falls back to the default path. The library server expands a leading ~ to your home folder, and it creates the folder for the database file if the folder does not exist.

Note

The rate limits are fixed inside the search server. Only the PubMed key raises a limit. The two contact emails and the Semantic Scholar key are passed to those services but do not change how fast PRIMA Scholar sends requests.

Where to Set Them

Where you put a setting depends on how you installed PRIMA Scholar.

Plugin Install in Claude Code

On the plugin route the servers take their settings from the environment that Claude Code starts in. Any key or email you have not exported reaches the search server as empty. An unexported RESEARCH_LIBRARY_PATH reaches the library server as the default path.

1. Open your shell profile, for example ~/.zshrc on macOS, in a text editor.

2. Add one export line for each setting you want, with your own value in place of the placeholder.

   export CORE_API_KEY=your-core-api-key
   export PUBMED_API_KEY=your-pubmed-api-key
   export CROSSREF_MAILTO=you@example.com

3. Save the file, then open a new terminal window so the settings take effect.

4. Start Claude Code from that new terminal window so the servers can read the settings.

Installer Install in One Workspace

The installer registers both servers in ~/.claude.json. Each server entry there has an env block, and that block holds the settings.

1. Open ~/.claude.json in a text editor and find the prima-scholar-search entry under mcpServers.
2. Add each key or email to its env block, with the setting name on the left and your value on the right.
3. Change RESEARCH_LIBRARY_PATH in the prima-scholar-library entry if you want the library somewhere else.
4. Save the file, then quit Claude Code and start it again.

Running the installer again keeps every setting already in those env blocks and adds only defaults that are missing. Versions before 2.2.1 rebuilt the search server’s env block on re-registration and dropped PUBMED_API_KEY, SEMANTIC_SCHOLAR_KEY and CORE_API_KEY. If you updated with an older installer, check that your keys are still there.

What Happens Without a CORE Key

A search that includes CORE and runs without CORE_API_KEY still returns results from the other databases. The response carries a missingApiKeys entry saying that CORE has no key and where to get a free one. If CORE is the only database you asked for, the search stops with a message that no sources are available.

scholar_full_text also skips CORE without a key. It then tries Europe PMC, arXiv and bioRxiv/medRxiv, which return a download link but never the text itself.

Keeping Keys Private

Caution

Never paste an API key into a conversation with Claude. Anything you type in a conversation is sent to Anthropic and kept in your conversation history. Put keys in your shell profile or a configuration file on your own computer, as this page describes.

Each key travels only to the service it belongs to. The PubMed key is added to PubMed request addresses, the Semantic Scholar key goes in a request header to Semantic Scholar, and the CORE key goes in a request header to CORE. The two contact emails go to OpenAlex and CrossRef. Privacy and Your Data lists everything PRIMA Scholar sends and keeps.

Files that hold keys, such as your shell profile and ~/.claude.json, belong on your own computer only. Keep them out of shared folders and out of any git repository.