API and MCP: 401, 402, 403, 429, or a missing tool

401 Unauthorized

No Authorization: Bearer nhm_… header, a revoked or expired key, or a plan below Pro. Keys are re-checked on every request, so a key that worked last month stops the day the plan lapses.

Fix: create a key under Settings, API keys on a Pro or Enterprise account, and send it as a bearer token.

402 plan_upgrade_required

The endpoint needs a capability the plan does not have: DMARC reports or SEO on Free, Local SEO on Starter, scanner issue reports and finding verdicts below Pro. The body names required_plan.

Fix: upgrade, or use the read that the plan allows (GET /api/seo-results/policy is open on every plan so you can see what is allowed).

403 Forbidden

One of four things: the route is not open to API keys at all ("This endpoint is not accessible via API key"; many dashboard routes are reachable over MCP only); the key lacks the resource scope for the route; the request changes state, or is a GET that runs a live scan (/api/checkup, /api/seo-check and the other scoring endpoints), and the key has no write scope (Enterprise only); or the resource belongs to another account.

Fix: use the MCP tool for a route keys cannot reach, or mint a key with the scope. A key's scopes cannot be edited after creation.

429 Too Many Requests

The key's hourly rate limit (1,000 by default, up to 10,000 at creation), or a per-plan manual-scan allowance. Retry-After and the body say which and when.

409 idempotency_mismatch

A request_key was reused for a different paid request. Generate a fresh key for a new run, and use get_local_seo_operation to read back the earlier one.

A tool is missing from tools/list

The list is filtered to the key's scopes and the account's plan. A missing tool means a missing scope (or, for write tools, a Pro key or no write). Mint a new key with the scope rather than rewording the prompt.

isError: "read-only"

The tool changes state and the key has no write scope. Live-scan tools count as writes even when they do not modify the target, because they spend allowances and contact upstream providers.

The connection works but Claude says the server has no tools

Check the header is sent exactly as Authorization: Bearer nhm_… (a stray space or a missing Bearer is the usual cause), and that the URL is https://nhmohio.com/api/mcp. Confirm with the tools/list curl in Connecting the MCP server.

Related

• API keys
• The REST API