NEON API token¶

neon-mcp needs no credentials for discovery: NEON's product, site, location, release, taxonomy and prototype-dataset records are public. A NEON API token is required only when a tool has to list or fetch actual data or prototype files, or trace samples. This page shows how to create a token, what to call it, how to hand it to neon-mcp and how to check that NEON accepts it.

In short: sign in at the NEON Data Portal, open My Account, click GET API TOKEN, copy the token, and put it in the environment neon-mcp starts in as NEON_TOKEN. Then run neon-mcp --check and look for "tokenAccepted": true.

Why a token is needed¶

Since version 0.11.0 of the NEON Data API (June 2026) the following endpoints are marked Requires Authentication. Without a token they answer HTTP 403 with the body {"error":{"status":403,"detail":"Access Denied"},"data":null}¹:

Everything else — /products, /sites, /locations, /releases (list, detail, products, sites), /taxonomy, /samples/classes, /samples/supportedClasses, /prototype/datasets and the GraphQL endpoint — is anonymous. Data availability per site and month is part of the public product and site records, so neon-mcp can tell you what exists without a token; it needs the token to tell you where the files are and to fetch them.

Create a token¶

The token belongs to a free NEON Data Portal account¹.

1. Create an account (once). On data.neonscience.org click Sign In at the top right. Tick the box next to I agree to the terms of service and privacy policy, then choose a sign-up button: a Google account, CILogon (GitHub, ORCID or your university login), or an email address and password⁴. Finish any verification NEON asks for; tokens are issued only to authenticated, verified accounts¹.
2. Open My Account. Signed in, go to data.neonscience.org/myaccount³.
3. Generate the token. Scroll to the bottom of the page and click GET API TOKEN. After a moment the token appears⁵.
4. Copy it. Click Copy next to the token⁵ and store it straight away where the next section says. A password manager is a good place to keep a second copy.

The same section of My Account lists your tokens. The ⋯ menu to the right of a token disables or deletes it⁴. NEON documents no expiry date. If a token may have leaked, disable or delete it and generate a new one¹.

Call it NEON_TOKEN¶

Store the token in an environment variable named NEON_TOKEN. That is the name NEON's own tutorials use (in .Renviron for R, in a .env file for Python)⁵, and the name the neonutilities examples read with os.environ.get("NEON_TOKEN")⁶. One variable then serves neon-mcp, your neonUtilities scripts and curl -H "X-API-Token: $NEON_TOKEN". neonUtilities itself does not read the variable; you pass it as token=. neon-mcp picks it up on its own.

Give the token to neon-mcp¶

read -rs NEON_TOKEN && export NEON_TOKEN     # paste the token, press Enter
claude mcp add neon -s user -e NEON_TOKEN="$NEON_TOKEN" -- neon-mcp --transport stdio

"env": { "NEON_TOKEN": "paste-your-token-here" }

uv run --env-file .env neon-mcp --check     # uv loads the file for this command
set -a; . ./.env; set +a                    # or export it into the current shell

neon:
  api_token: "paste-your-token-here"

There is deliberately no command-line flag for the token: arguments are visible in the process list and shell history. An environment variable wins over the YAML file.

Check that NEON accepts it¶

Run the check in the same environment the server will run in:

neon-mcp --check

It makes one small NEON request and prints one line of JSON, for example (rateLimit omitted here):

{"ok": true, "version": "0.1.0", "tokenConfigured": true, "tokenAccepted": true, "apiReachable": true, "apiStatus": 200}

A rejected token is worse than none: NEON refuses every request that carries it, public endpoints included, so discovery tools fail with code: "forbidden" until you fix or unset it. Inside an agent, neon_ping with check_api=true reports the same thing: tokenConfigured, tokenSource, and a note when NEON rejects the token.

Rate limits¶

NEON rate-limits the API globally across all endpoints. Each limit has a burst (requests you can make at once) and a rate at which the burst refills. A token raises both substantially²:

Every response carries X-RateLimit-Limit (the burst), X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the burst refills in full). When the limit is exceeded the API returns HTTP 429 with a RetryAfter header and the body {"message":"API rate limit exceeded"}. neon-mcp shares one HTTP client across all tools, slows down when X-RateLimit-Remaining runs low, and retries a 429 after the RetryAfter interval (it keeps 10 % under both limits), so agents rarely hit the limit — but a token remains the single most effective way to speed up a heavy session.

NEON reserves the right to change these limits at any time; the response headers are authoritative².

What happens without a token¶

• Discovery tools (products, sites, locations, availability, releases, taxonomy, prototype datasets) behave identically with or without a token, apart from the lower rate limit — except that neon_get_prototype_dataset leaves out the dataset's files (with a note) unless a token is set, and fails with auth_required if you ask for files explicitly.
• Three tools need a token: neon_list_files, neon_download_files (for NEON data and prototype files; document downloads need none) and neon_get_sample. Without one they fail before any request with a structured error, code: "auth_required", whose message names NEON_TOKEN and links to data.neonscience.org/myaccount. The tool reference marks each token-only tool, and neon_ping reports whether a token is available.