Orizn Visa API

Claude Desktop · Claude Code · Cursor

MCP server

Give your AI assistant real visa data over the Model Context Protocol. Five tools, one npx command, no build step.

What was executed to write this page

orizn-visa-mcp 1.2.0 was launched over stdio and driven with raw JSON-RPC: initialize, tools/list, and tools/call for quick_visa_check and get_coverage_stats, both with and without an API key. Every output block on this page is that server's actual stdout.

Before you start

  • Node.js 18 or later. The server speaks MCP over stdio; anything that can launch a stdio server works.
  • An MCP client: Claude Desktop, Claude Code, Cursor, or your own.
  • An Orizn API key. Free tier: 50 requests/month, no credit card — get one at visa.orizn.app/visa-api. It is 5 requests until you confirm your email, so click the link in the confirmation mail.
Get a free API key

Walkthrough

1. Run it once, before touching any config

Nothing to clone, nothing to build. This confirms Node can fetch and start the server.

Terminal
npx -y orizn-visa-mcp

With no key set, the server still starts — it tells you what is missing and keeps the one tool that needs no key:

Output · stderr, trimmed — the JSON log lines around it carry a ts field
  Orizn Visa MCP — no API key found.
  Every tool except get_coverage_stats will fail until you set one.

  Free key, 10 seconds, no credit card:  https://visa.orizn.app/visa-api
  50 requests/month · all 15 languages · 199 passports

  Then add it to your MCP config:  "env": { "ORIZN_API_KEY": "orizn_visa_..." }
  or start the server with:        npx orizn-visa-mcp --api-key orizn_visa_...

{"level":"info","message":"Orizn Visa MCP server 1.2.0 started on stdio"}

2. Add it to your client's config

The block is identical for every client. Only the file it goes in changes.

claude_desktop_config.json / .mcp.json / Cursor MCP settings
{
  "mcpServers": {
    "orizn-visa": {
      "command": "npx",
      "args": ["-y", "orizn-visa-mcp"],
      "env": {
        "ORIZN_API_KEY": "orizn_visa_..."
      }
    }
  }
}
  • Claude Desktop, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop, Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Claude Code: .mcp.json at the root of the project
  • Cursor: Settings → MCP → add a new server

3. Restart the client and ask a question

Restarting is required — clients read the MCP config at launch. Then ask, in plain language:

  • Do I need a visa to travel from France to Thailand?
  • What documents do I need as a US citizen visiting China?
  • Compare Thailand, Vietnam and Indonesia for a Brazilian passport.

Under the hood the assistant calls a tool. This is the real payload that comes back for the first kind of question — captured by driving the server directly:

Output · tools/call → quick_visa_check { passport: FRA, destination: JPN }
{
  "passport": "FRA",
  "destination": "JPN",
  "requirement": "visa_free",
  "visa_free_days": 90,
  "visa_required": false,
  "last_verified": "2026-05-08"
}

4. Confirm the wiring without leaving the chat

get_coverage_stats is the only tool that needs no key, so it isolates a network problem from a key problem. Ask “how big is the Orizn visa database?” and you get:

Output · tools/call → get_coverage_stats {} — trimmed to coverage and requirement_distribution; the full payload also returns supported_languages, api_version and docs
{
  "coverage": {
    "visa_details": 40027,
    "passports": 199,
    "destinations": 202,
    "passport_index_pairs": 39999,
    "translations": 560378,
    "languages": 15
  },
  "requirement_distribution": {
    "visa_required": 13403,
    "visa_free": 13333,
    "e_visa": 7617,
    "visa_on_arrival": 4695,
    "eta": 903,
    "no_admission": 43,
    "not_applicable": 11,
    "partial_restrictions": 11,
    "admission_refused": 9,
    "special": 2
  }
}

If that works and the others do not, it is the key, not the network. If that fails too, the client never managed to launch the server.

When it goes wrong

Every failure the integration can hand you, with the message it actually prints.

No API key reached the server

JSON-RPC -32600
"No Orizn API key. Get a free one in 10 seconds at https://visa.orizn.app/visa-api (50 requests/month, no credit card), then set ORIZN_API_KEY=<key> in the `env` block of your MCP server config, or start the server with --api-key <key>. Restart the client afterwards."

Put the key in the env block of the config, not in your shell. Restart the client.

Alpha-2 country code

JSON-RPC -32602
"passport" must be an ISO 3166-1 alpha-3 country code — three letters, e.g. FRA, JPN, USA. Got "FR".

Use alpha-3. The error is raised before any request is sent, so it costs no quota.

Key is wrong, revoked, or has whitespace

HTTP 403
The API answers {"error":"Invalid API key","message":"Get your free API key at https://visa.orizn.app/visa-api"}

Re-copy the key from the dashboard. A trailing space is the usual culprit.

Free key calling compare_destinations or check_transit_visa

HTTP 403
The tool reports that it requires the Hobby plan or above.

Use check_visa_requirement per pair, or upgrade. Hobby is $9/month for 10,000 requests.

Monthly quota spent

HTTP 429
{"error":"Monthly limit exceeded (50 req/month on free plan). Upgrade at https://visa.orizn.app"} with X-RateLimit-Remaining: 0

Wait for the monthly reset or upgrade. get_coverage_stats keeps working.

The no-key, invalid-code, rejected-key and plan-gate rows were reproduced by driving the server over stdio. The quota row is quoted from the API source: the key used to write this page is uncapped, so exhaustion could not be triggered on purpose.

End to end: planning a trip inside the assistant

Once the server is connected, the assistant stops guessing and starts citing. A realistic exchange, and what each turn actually calls:

  • “I have a Brazilian passport and 3 weeks off in March — compare Thailand, Vietnam and Indonesia.” → compare_destinations, one call, three destinations, three requests of quota.
  • “Vietnam looks best. What do I actually need?” → check_visa_requirement for BRA→VNM: documents, application steps, fees, processing days, passport validity, vaccinations, insurance.
  • “I connect through Istanbul for 11 hours — can I leave the airport?” → check_transit_visa for BRA→TUR, which answers airside vs landside and the free transit hours the hub grants.

The value is not that the assistant answers — it already did that. It is that every one of those answers now carries a last_verified date, and that the three calls agree with each other because they hit one dataset.

Source & reference

Full API reference →GitHub →npm →

Other integrations

REST API · curl · any languageorizn (npm) · JavaScript / TypeScript SDKorizn (PyPI) · Python SDKorizn (crates.io) · Rust SDK@orizn/langchain · LangChain.js tools@orizn/react · React componentNext.js · Route handler · server-side

50 requests a month, no credit card

All 15 languages included on the free plan. Hit a wall with this tutorial? Mail [email protected] — a tutorial that does not work is a bug.

Get a free API keyAPI reference