Loading...
Loading...
AI-assistant invocation surface
The WhereNext MCP server lets AI assistants — Claude Desktop, Cursor, OpenAI agents, Perplexity, any Model Context Protocol client — invoke our relocation intelligence directly: shortlist countries, compare destinations, score readiness, estimate first-year cost, look up sources, run natural-language queries, and — with explicit user consent — submit a partner-intro request. 9 tools total. Streamable HTTP transport at /api/mcp, plus an stdio entry for local installs.
POST https://getwherenext.com/api/mcpGET https://getwherenext.com/.well-known/mcp.jsonnpx tsx scripts/mcp-server.ts9 tools total. 8 are read-only and safe to call without confirmation. The 9th — request_provider_handoff — mutates state (creates a partner-intro lead) and requires explicit consent from the end user before invocation.
shortlistRead-onlyRank countries server-side from caller-supplied dimensional weights.
compareRead-onlySide-by-side scoring for 2–4 countries with per-dimension winners.
relocation_readinessRead-only0–100 readiness score, severity-tagged blockers, top next step.
first_year_costRead-onlyMove-in cash + monthly recurring + one-time cost for a destination + household.
advisor_packetRead-onlyDisclosure copy, required fields, questions, document checklist per provider category.
source_lookupRead-onlyFind canonical WhereNext sources (datasets + visa registry) by free-text query.
nl_queryRead-onlyFree-form question parsed into passport / household / budget / persona / dimension weights, then scored.
plan_relocationRead-onlyOne unified workflow: NL parse or case → shortlist → per-destination readiness + cost + recommendation.
request_provider_handoffMutating · requires consentSubmit a consented vetted-provider-intro on the user's behalf. REQUIRES consent record with the exact disclosure copy.
Add to claude_desktop_config.json or your client's MCP config:
{
"mcpServers": {
"wherenext": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-http", "https://getwherenext.com/api/mcp"],
"env": {
"MCP_BEARER_TOKEN": "your-token-here"
}
}
}
}MCP uses JSON-RPC 2.0 over Streamable HTTP. The handshake is initialize → server returns capabilities + an Mcp-Session-Id header on success. Subsequent calls include that header.
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" }
}
}'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" \
-H "Mcp-Session-Id: <session-id-from-initialize>" \
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'request_provider_handoffThis is the only tool that mutates state. It creates a row in public.partner_intros and triggers a human review at WhereNext (2 business day SLA). Agents calling it MUST:
advisor_packet tool, per category).consent.disclosure field. Every row's consent_trail is manually audited.Fabricating consent on a user's behalf is a serious safety violation and will lead to the bearer token being revoked. See /providers for the policy WhereNext applies after a lead lands.