Brave Search MCP: 422 SUBSCRIPTION_TOKEN_INVALID

Fix Brave Search MCP 422 SUBSCRIPTION_TOKEN_INVALID

TL;DR

Your Brave API key is missing, wrong, or not reaching the server. Put BRAVE_API_KEY in the env block of the MCP config (not in HTTP headers), verify the key is valid in the Brave dashboard, and restart. The 422 is Brave's way of saying the subscription token is invalid.

The exact error:

422 SUBSCRIPTION_TOKEN_INVALID

Steps

1. Confirm the key is actually set in env

Open your MCP config and check the entry looks like this:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": { "BRAVE_API_KEY": "[your Brave API key]" }
    }
  }
}

Success check: the key sits under env, not in headers, not in args. Keys in headers or args never reach the server process.

2. Verify the key itself

Log in to the Brave Search API dashboard and check:

• the key exists and is not expired
• the key has no leading or trailing spaces when pasted
• you have not exceeded the free monthly credits (the Search plan includes $5 in free credits)

Success check: a test search from the dashboard works with the same key.

3. Restart and retest

Fully quit the client (Claude Desktop needs all processes ended, not just the window closed) and reopen it. Ask it to run a brave search.

Success check: results come back instead of the 422.

When this applies

• Every bravesearch call fails with `422 SUBSCRIPTIONTOKEN_INVALID`.
• You recently registered, reinstalled, or moved the config between clients.

When it does not apply

• The server fails to start with "package not found" or a module error. That is the wrong package name problem: it must be @brave/brave-search-mcp-server.
• The server starts but Codex says it is "not logged in". Do not try to log in; Brave MCP takes an API key, not OAuth. Use --brave-api-key or the env var.

Tool compatibility

• @brave/brave-search-mcp-server npm package
• Claude Desktop, Claude Code, Cursor, Codex
• Node.js 18+

Why it happens

The server sends your key to Brave's API as the X-Subscription-Token header. When the key is absent or wrong, Brave answers 422 SUBSCRIPTIONTOKENINVALID, which the server surfaces verbatim. The most common cause is putting the key somewhere the server never reads: HTTP headers in a remote config, a quoted empty string, or an env block that a registry UI silently dropped.

Edge cases

• Registry UIs (SlashMCP and similar) sometimes preprocess configs; if the key looks right but the 422 persists, re-register the server from scratch with the corrected package name and key.
• Smithery-installed servers can overwrite your manual config; check the config file after any reinstall.
• A key that worked yesterday and 422s today usually means it expired or hit the credit cap; regenerate it in the dashboard.