switchwize-mcp

SwitchWize MCP Server

Read-only Model Context Protocol server for SwitchWize public rate and index data. It exposes 16 tools with input/output schemas, MCP read-only annotations, text fallbacks, and structured content for clients that support it.

Start

From this directory:

npm run start

From the repository root:

npx tsx --env-file=.env.local packages/mcp-server/src/server.ts

Smoke Test

npm run smoke        # dev path, via tsx against src/server.ts
npm run smoke:dist    # against the built dist/index.js — what a real npx install runs

Both start the MCP server, run the protocol handshake, list tools, and call tools. smoke:dist additionally calls all 16 tools with sample arguments and lets the MCP SDK client validate every response's structuredContent against its declared outputSchema — the same check an external agent client makes.

Publishing

This package is published to npm as switchwize-mcp so npx -y switchwize-mcp works standalone. It is a small stdio bridge to SwitchWize's public hosted MCP endpoint, so it needs Node.js and network access only—no monorepo checkout, SwitchWize account, API key, database URL, or telemetry credentials.

npm run build        # bundles src/server.ts -> dist/index.js (also runs automatically via prepublishOnly)
npm run smoke:dist    # verify the built artifact against all 16 tools before publishing
npm run verify:deposit-release # per category: released ones need exact feed/MCP parity, unreleased ones must fail closed; DEPOSIT_RELEASE_REQUIRED (default hysa) names what must be released
npm publish           # enforces the deposit release gate; requires npm publishing access

By default the bridge connects to https://www.switchwize.com/api/mcp. Set SWITCHWIZE_MCP_URL only when intentionally connecting it to a compatible alternate endpoint.

Tools

• get_top_rates
• get_top_hysa_rates
• get_bank_gap
• compare_switch_savings
• get_rate_freshness
• get_index_dataset
• get_bank_gap_index
• get_reality_score
• get_card_offers — current welcome-bonus offers, verified and sourced
• get_transfer_bonuses — current point-transfer bonuses with best-ever-for-route
• get_card_changes — recent verified fee/APR changes
• get_reward_valuations — cents-per-point valuations per reward currency
• best_move_this_week — dollar-ranked actions for a supplied wallet of card ids
• get_cd_rollover_rules — verified bank CD renewal, grace-period, opt-out, and penalty rules
• get_card_downgrade_path — verified product-change targets and fee-refund windows
• get_fed_hike_pass_through — how much of the latest Fed hike each tracked savings account has passed through to savers

All tools are read-only and delegate to the same validated public-data tool functions used by /api/public/tools. Production records aggregate request, tool, outcome, client-label, and latency counters for 90 days. It never stores tool arguments, response bodies, IP addresses, or financial values.

Prompts

Canned workflows a client can surface directly (e.g. as slash commands), instead of requiring the user to phrase the right freeform question. See src/lib/mcp/prompts.ts.

• audit_savings — is the user losing money in their current savings account, and by how much per year.
• audit_wallet — given a wallet of held cards, this week's highest-value move.
• prepare_cd_maturity — what happens automatically when a CD matures, and whether the rollover rate is competitive.

Resources

Reference material an agent can read once and cite, instead of re-deriving (or inventing) it from a tool response's summary field. See src/lib/mcp/resources.ts.

• switchwize://methodology — how SwitchWize sources and verifies data.
• switchwize://freshness-policy — what freshnessStatus/asOf/verified_at mean and how to act on them.
• switchwize://tools — the full tool catalog with suggested chaining.
• switchwize://supported-institutions — how to get the current live institution list per category (not hardcoded, since coverage grows).

Eval suite

src/lib/mcp/eval.ts calls every tool in-process with realistic sample arguments (~22 cases across the 16 tools, including a few deliberate not-found lookups) and scores the real response against what a client actually depends on — did it throw, does it carry freshnessStatus, reasonable latency. Runs weekly via /api/cron/mcp-weekly-quality-report (not yet registered on cron-job.org — see CLAUDE.md's cron table) alongside the 7d/30d usage telemetry, stores the result for /admin/mcp to display, and emails a summary if ADMIN_EMAIL/CEO_EMAIL and RESEND_API_KEY are set.