Skip to content

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 files or trace samples. This page explains why, where to get a token, how to hand it to neon-mcp, and what changes once it is set.

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}1:

Endpoint family Paths
Data files GET /data/{productCode}/{siteCode}/{year-month} (and /{filename}), GET /data/package/{productCode}/{siteCode}/{year-month}
Data query GET /data/query, POST /data/query
Release-pinned data GET /releases/{releaseTag}/data/... (all variants)
Sample tracking GET /samples/view, GET /samples/download

Everything else — /products, /sites, /locations, /releases (list, detail, products, sites), /taxonomy, /samples/classes, /samples/supportedClasses, /prototype/* 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.

Getting a token

  1. Sign in (or create a free account) at the NEON Data Portal: data.neonscience.org/myaccount3.
  2. In My Account, open the API tokens section and generate a token.
  3. Copy it somewhere safe and treat it exactly like a password.

NEON accepts the token either as the X-API-Token request header or as an apiToken query parameter1. neon-mcp always sends the header form, so the token never appears in request URLs, access logs or the signed download links it returns.

Giving the token to neon-mcp

export NEON_MCP_NEON__API_TOKEN="paste-your-token-here"
# or the variable neonUtilities documents, accepted as a fallback:
export NEON_TOKEN="paste-your-token-here"

neon-mcp reads NEON_MCP_NEON__API_TOKEN first, then NEON_TOKEN, then NEON_API_TOKEN. Pass it to a client at registration, e.g. claude mcp add neon -s user -e NEON_TOKEN=... -- neon-mcp --transport stdio, or through a systemd EnvironmentFile=.

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

Pass the file with --config. Keep it out of version control — config.yaml and *.local.yaml are already in the repository's .gitignore.

Each caller sends its own token in the X-API-Token header, for example claude mcp add --transport http neon https://neon-mcp.example.org/mcp --header "X-API-Token: $NEON_TOKEN". The server honours the header only when its server.public_base_url is https:// (TLS in front of it), so a token never crosses the network in clear text; server.allow_insecure_header_token overrides this for local testing only. An operator's configured token is not lent to anonymous HTTP callers unless server.share_config_token_over_http is set.

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

Never commit a token

Do not paste a token into a repository, a checked-in MCP client configuration, an issue, or a chat transcript. If a token leaks, revoke it at data.neonscience.org/myaccount and generate a new one. neon-mcp sends it only as the X-API-Token header and only to data.neonscience.org, never logs it, never echoes it in tool results or error messages, never puts it in cache keys (only a one-way hash), and never places it in MCP requestState (which round-trips through the client).

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 substantially2:

Mode Burst Sustained rate Applied per
Anonymous 200 requests 2 requests/s IP address
With API token 2 000 requests 8 requests/s token

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 authoritative2.

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.
  • Three tools need a token: neon_list_files, neon_download_files (for NEON data files; prototype and 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 the settings above and links to data.neonscience.org/myaccount. The tool reference marks each token-only tool, and neon_ping reports whether a token is available.

  1. NEON Data API — Authentication. https://data.neonscience.org/data-api/authentication/ ↩↩

  2. NEON Data API — Rate Limiting. https://data.neonscience.org/data-api/rate-limiting/ ↩↩

  3. NEON Data Portal — My Account. https://data.neonscience.org/myaccount ↩