WhereNext MCP server

Tools

16 tools total. 15 are read-only and safe to call without confirmation. The 16th — request_provider_handoff — mutates state (creates a partner-intro lead) and requires explicit consent from the end user before invocation.

• shortlistRead-only

  Rank countries server-side from caller-supplied dimensional weights.

• compareRead-only

  Side-by-side scoring for 2–4 countries with per-dimension winners.

• relocation_readinessRead-only

  0–100 readiness score, severity-tagged blockers, top next step.

• first_year_costRead-only

  Move-in cash + monthly recurring + one-time cost for a destination + household.

• advisor_packetRead-only

  Disclosure copy, required fields, questions, document checklist per provider category.

• source_lookupRead-only

  Find canonical WhereNext sources (datasets + visa registry) by free-text query.

• nl_queryRead-only

  Free-form question parsed into passport / household / budget / persona / dimension weights, then scored.

• plan_relocationRead-only

  One unified workflow: NL parse or case → shortlist → per-destination readiness + cost + recommendation.

• eligibility_verdictRead-only

  Deterministic, regulator-cited verdict on whether an applicant meets a visa pathway's published financial threshold (income / savings / age). A $0-minimum programme is reported as 'near', never a confident pass; sources never fabricated.

• claim_verifyRead-only

  Verify a structured relocation-threshold claim against WhereNext's cited figure: AGREES / DISAGREES_WITH_FIGURE / PARTIALLY / UNVERIFIED / UNMODELLED. A comparison to a named source, never a truth judgment; DISAGREES always carries a programme-specific citation.

• descent_eligibilityRead-only

  Conservative, primary-source-cited verdict on whether you can claim citizenship BY DESCENT through a given ancestor (Canada, Italy, Ireland, Poland): eligible / likely / not_eligible / needs_more_info with the exact rule, any 2024-2026 change (Bill C-3, Law 74/2025), the next step, and the named authority + primary source + verified date. Never a fabricated rule; never a confident verdict on a nuanced case.

• tax_residencyRead-only

  Conservative, authority-cited 183-day tax-residency verdict for 8 countries (PT/ES/DE/TH/CY/AE/GB/US): likely_resident / likely_not_resident / depends_tie_breaker / needs_professional with the tax-year basis, named tax authority + verified date, and the official statutory-test link. UK SRT + US SPT defer to the official test. Decision support, not tax advice.

• pet_importRead-only

  Conservative, authority-cited pet (dog/cat) import timeline for the EU/UK/AU/JP/CA/AE: ordered official steps + how far ahead to start (the rabies-titer wait adds 3 months EU/UK or 180 days AU/JP; the UAE gates the titer on MOCCAE's low-risk list), quarantine, named animal authority + verified date, official checker URL. Defaults to the longer path when origin is unsure. Decision support, not a customs guarantee.

• golden_visa_matchRead-only

  Source-cited matcher ranking the ACTIVE golden-visa (residency-by-investment) programmes for a budget + goals (Schengen / EU-citizenship / family) + presence tolerance: each returned eligible / borderline / over_budget with the verbatim minimum, presence days, years-to-citizenship, Schengen + EU flags, closure-risk, and the named official source + verified date. Closed programmes never shown; open-reforming flagged. Decision support, not legal advice.

• corridor_readinessRead-only

  Composes one from→to view of which WhereNext primary-sourced checks (descent, tax-residency, pet-import, visa-eligibility) are modelled for a corridor — each ready_to_check or not_yet_modeled, deep-linked + cited. Honest by construction: an unsupported pair is not_yet_modeled, never fabricated. Maps coverage + provenance; computes no verdict itself.

• request_provider_handoffMutating · requires consent

  Submit a consented vetted-provider-intro on the user's behalf. REQUIRES consent record with the exact disclosure copy.

Raw protocol example (curl)

MCP uses JSON-RPC 2.0 over Streamable HTTP. The endpoint is stateless: every request is built fresh and authenticated independently, so there is no session to carry between calls — each request just sends the bearer token plus the MCP-Protocol-Version header. (For a managed local bridge, use mcp-remote as shown above.)

1. initialize

curl -X POST https://getwherenext.com/api/mcp \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl-client", "version": "1.0.0" }
    }
  }'

2. tools/list

curl -X POST https://getwherenext.com/api/mcp \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'