API-318: Add nansen mcp verify — client-independent authenticated MCP setup verification

[gulshngill]

Problem

MCP clients can list the hosted Nansen MCP server's tools without a valid API key — the server serves tools/list (and free tools) unauthenticated, and tool-argument validation also runs before auth. So a broken credential setup looks successful until the first paid data call fails. There was no user-facing way to verify an MCP setup end to end.

Solution

New diagnostic command — client-independent, runnable with zero checkout:

npx -y nansen-cli mcp verify --api-key <key>

It performs a real authenticated data-path check, not just discovery:

1. mcp-api-key — resolves the key (--api-key → NANSEN_API_KEY → ~/.nansen/config.json) and reports the masked key + source.
2. mcp-server — JSON-RPC tools/list for reachability (explicitly labelled "unauthenticated; reachability only").
3. mcp-auth — tools/call on the cheapest paid canary tool (nansen_score_top_tokens, ~1 credit). Server error text is mapped to actionable next steps: key rejected → check the client's NANSEN-API-KEY header / rotate at app.nansen.ai; insufficient credits → top up; rate limited → retry (and the setup is not reported verified).

Verified ⟺ the paid canary call succeeds with a well-formed result. On failure the command exits non-zero through the CLI's unified error envelope (code: MCP_VERIFY_FAILED); --json returns the structured checks (failure carries them in details). Success message is honest about scope: the CLI proves the key works against the server's paid data path and reminds the user to put that same key in their client's header; README documents an in-client canary prompt for that final hop.

No new dependencies — the stateless streamable-HTTP server needs exactly two fetch POSTs (JSON or SSE-framed responses both handled).

Changes

• src/mcp-verify.js (new) — MCP JSON-RPC probe + checks + report formatting
• src/cli.js — mcp verify wiring, HELP entry; bare nansen mcp prints usage only (never runs the paid probe implicitly)
• src/doctor.js — export resolveAuthConfig, extract shared formatChecks (doctor output unchanged, proven by existing tests)
• src/schema.json — mcp verify command schema
• README.md — "Verify your MCP setup" section + troubleshooting row
• src/__tests__/mcp-verify.test.js (new, 22 tests) — mocked-fetch coverage of SSE/JSON parsing, every auth-failure mapping, timeout/network/unparseable paths, key precedence, report format, and the non-zero --json exit contract
• .changeset/mcp-verify.md — minor

Testing

• npm test: 2310 passed, 2 skipped (57 files) — all fetch mocked. Re-run after merging main (2026-08-28).
• npm run lint: clean
• Live smoke against production MCP: bogus key → key-rejected mapping + exit 1; valid key → verified + exit 0; --json failure → single machine-readable envelope; bare nansen mcp → usage, no network call

Note for docs: the verify one-liner is worth adding to the MCP "Connecting" page on docs.nansen.ai (external repo, out of scope here).

🤖 Generated with Claude Code

[nansen-pr-reviewer]

pr-reviewer Summary for #1b52831

✅ No issues found

The code review completed successfully with no findings.

Review effort: 3/5 (Moderate)

Summary

This PR adds nansen mcp verify — a well-designed diagnostic command that closes a real gap: MCP's unauthenticated tools/list gave false confidence that a broken key setup was working. The implementation is clean and the approach is sound.

Overall assessment: The production code is correct, the error-handling paths are thorough, and the test suite covers every important branch (SSE vs JSON responses, all auth-failure mappings, timeout, network failure, malformed results, key-precedence, and the non-zero --json exit contract). No findings.

Specific things reviewed and confirmed correct:

• parseArgs / flags['api-key'] guard — The boolean-flag whitelist in parseArgs does not include api-key, so a valueless --api-key correctly lands in flags (not options). The if (flags['api-key']) guard at line 938 catches this precisely, with a second guard for null/array values from JSON-parsed repeated flags.
• tools/list sent unauthenticated — The mcpRequest call for tools/list omits apiKey, confirmed both in code and in the test that asserts listCall[1].headers does not have NANSEN-API-KEY.
• Auth-failure classification ordering — Rate-limit matched before credits (the comment explains why: "credit rate limit" text would match both). The mixed-text test at line 170 pins this.
• HTTP non-2xx + unparseable body path — McpRequestError carries status but no rpcMessage; the catch block in runMcpVerifyChecks synthesizes { error: { message: text } } and passes error.status as httpStatus to authFailureCheck, so the HTTP status code still participates in the regex match. ✓
• isRpcError coverage — Handles message.error present, message.result.isError === true, and the top-level message.isError === true variant. All tested.
• doctor.js refactor — formatChecks extracted cleanly; formatDoctorReport output is byte-identical. resolveAuthConfig and check are exported without behavioural change.
• Changeset — minor bump is correct for a new user-facing command. Package name nansen-cli is correct.
• schema.json — mcp.verify entry is present with api-key, url, and json options. Schema test at line 338 pins it.
• Telemetry/offline classification — isMcpUsage correctly identifies bare nansen mcp (usage-only, no network) vs nansen mcp verify (live call), suppressing background telemetry for the former.

---

Token usage: 18,732 input, 5,867 output, 867,800 cache read, 53,422 cache write | Usage Guide

New pushes are reviewed automatically with a 10-minute cooldown between reviews. To request a review at any time, comment @nansen-pr-reviewer re-review.