DEV Community: Mathis Higuinen

Drop-in travel widgets — add visa rules, budgets & passport scores to any page with one line

Mathis Higuinen — Sat, 04 Jul 2026 23:56:01 +0000

A suite of embeddable widgets that pull live visa requirements, travel budgets, passport scores and country comparisons — no API wiring, no keys, one script tag. With a built-in affiliate parameter so your travel content can earn.

If you've ever run a travel blog, a nomad resource site, or a "moving abroad" landing page, you've hit the same wall I did: travel data is annoying to build. Visa rules change per passport/destination pair, budgets vary by city, and passport rankings shift constantly. You either scrape it, maintain it by hand, or wire up against an API and babysit the integration.

I got tired of that, so I built embed.orizn.app — a set of copy-paste widgets that render live travel data on any page. No backend, no API keys, no build step. You drop a <div> and a <script>, and you get an interactive component fed by the Orizn dataset (199 countries, 32 data points per passport/destination pair, 15 languages).

Here's how each one works.

1. Visa requirements

Shows entry requirements for a destination, adapting to the visitor's passport. Point it at a destination country and it does the rest.

<div id="orizn-visa"
     data-destination="VNM"
     data-affiliate="aff_e23154b8"></div>
<script src="https://visa.orizn.app/embed/visa.js" async></script>

data-destination — ISO 3166-1 alpha-3 code of where they're going (VNM = Vietnam)
data-affiliate — your affiliate ID (more on that below)

2. Travel budget

A quick cost-of-travel snapshot for a destination — the kind of "can I afford this?" widget that keeps readers on the page instead of bouncing to a search engine.

<div id="orizn-budget"
     data-destination="VNM"
     data-affiliate="aff_e23154b8"></div>
<script src="https://visa.orizn.app/embed/budget.js" async></script>

3. Passport score

Rank and reach of a given passport. Great for a "how powerful is your passport?" section, or as a hook on a citizenship/relocation page.

<div id="orizn-score"
     data-passport="FRA"></div>
<script src="https://visa.orizn.app/embed/score.js" async></script>

data-passport — ISO alpha-3 of the passport (FRA = France)

4. Country comparison

Side-by-side of two destinations for a single passport — visa treatment, and the differences that actually matter when someone's deciding between two places.

<div id="orizn-compare"
     data-country1="VNM"
     data-country2="THA"
     data-passport="FRA"
     data-affiliate="aff_e23154b8"></div>
<script src="https://visa.orizn.app/embed/compare.js" async></script>

data-country1 / data-country2 — the two destinations to compare
data-passport — the passport to evaluate them against

5. Trip checklist

A ready-to-go checklist tailored to a specific passport/destination pair — what to prepare before departure (documents, entry conditions, and the things travelers forget). This is the "actionable" widget: it turns your page from information into a to-do list readers can actually follow.

<div id="orizn-checklist"
     data-destination="VNM"
     data-passport="FRA"
     data-affiliate="aff_e23154b8"></div>
<script src="https://visa.orizn.app/embed/checklist.js" async></script>

data-destination — where they're going
data-passport — the passport they're traveling on
data-affiliate — your affiliate ID

The affiliate angle

Notice the data-affiliate attribute on most of these. That's the part I'm most excited about for content creators.

Every widget carries your affiliate ID, so the traffic you send through it is attributed to you. If you run a travel blog, a relocation newsletter, or a nomad community, you can embed genuinely useful tools and earn from the referrals they generate — instead of the widget being a pure cost center on your site. Grab your ID from embed.orizn.app and swap aff_e23154b8 for your own.

Try them live

Since this article is being read on a platform that (rightly) strips arbitrary <script> tags for security, the snippets above render as code, not as live components. To see the widgets actually running — and to configure your own with your affiliate ID — head to the live playground:

👉 embed.orizn.app

Everything is ISO-code driven, loads async so it won't block your page, and works with plain HTML — no framework required. Drop it into WordPress, a static site, Webflow, a landing page, whatever you've got.

If you build something with it, I'd love to see it — drop a link in the comments.

Your rate limiter is not a security control

Mathis Higuinen — Sat, 04 Jul 2026 01:14:47 +0000

Last week a bot pulled ~100% of one passport's data out of my visa API in a few minutes. My rate limiter — 3,000 calls/month on the free tier — never fired once. It didn't need to: a full passport is only ~195 calls.

That's the whole point of this post. Rate limiting protects your infrastructure cost. It does not protect your data. They're two different problems, and conflating them is how solo builders leak their most valuable asset.

Why volume limits fail against extraction

A rate limiter answers one question: is this client costing me too much per unit time? Targeted extraction is specifically designed to stay under that line. My scraper ran at ~25 req/min — trivial load — and would have needed only ~40,000 calls total to copy everything. Spread across a few free accounts, that's invisible to any per-key volume cap.

Volume is the wrong axis. The right axes are identity, coverage, and shape.

Defense 1 — Log the network, not just the key

The first thing that bit me: I could disable the API key, but I hadn't stored the source IP, so re-signup was free. Fix the log first.

ALTER TABLE visa_api_logs
  ADD COLUMN ip inet,
  ADD COLUMN country text;

CREATE INDEX idx_visa_logs_ip ON visa_api_logs (ip, created_at);

Populate ip from cf-connecting-ip (the real client behind Cloudflare — never trust remote_addr at the edge). Now a repeat offender is blockable at the network layer, and you can feed the IP straight to a Cloudflare firewall rule.

Defense 2 — Cap the resource, not the request count

Instead of "N requests/month," cap "N distinct destinations per passport per day." A legitimate user checks a handful of destinations for their own passport. A scraper wants all of them. The cap barely touches real usage and hard-stops a sweep.

Defense 3 — Detect the shape in real time

The sweep has a signature: dense, sequential, exhaustive coverage of a single from. That's detectable per key in a sliding window:

// Sketch: flag a key sweeping one passport across many destinations.
fn is_dump_pattern(hits: &[VisaHit], window: Duration) -> bool {
    let recent: Vec<_> = hits
        .iter()
        .filter(|h| h.ts.elapsed() < window)
        .collect();

    // Group by source passport, count distinct destinations.
    let mut by_passport: HashMap<&str, HashSet<&str>> = HashMap::new();
    for h in &recent {
        by_passport.entry(&h.from).or_default().insert(&h.to);
    }

    // One passport, many destinations, tight cadence = extraction.
    by_passport
        .values()
        .any(|dests| dests.len() > DUMP_THRESHOLD)
        && mean_interval(&recent) < Duration::from_secs(4)
}

Trip it → throttle that key hard (or 402 it) and log the IP. You're now reacting to behavior, not just counting.

The mental model

Split the two jobs explicitly:

Rate limiter → "don't cost me money." Cheap, coarse, per-key volume.
Extraction defense → "don't copy my dataset." Identity + coverage + cadence, network-aware.

If you only have the first one, you have a billing guardrail dressed up as security. Ask me how I know.

Anatomy of an API scrape: reading 251 requests like a crime scene

Mathis Higuinen — Fri, 03 Jul 2026 00:49:23 +0000

Last week someone tried to copy my visa API's database. They didn't succeed — they got 0.6% of it before I cut the key — but the 251 requests they left behind are a near-perfect teaching case for what targeted API extraction actually looks like from the defender's side.

Here's the forensic walkthrough.

The target

One endpoint:

GET /api/v1/visa?from={passport}&to={destination}

It returns the visa rule for a passport→destination pair — visa type, allowed stay, conditions. The full matrix is ~39,585 pairs. That matrix is the product.

The evidence

The attacker's requests weren't spread across the map. They were a sweep, one passport at a time:

Passport	Destinations pulled	Coverage
🇦🇪 UAE (ARE)	195	~100% of that passport's matrix
🇦🇺 Australia (AUS)	53	~1/4, interrupted
🇨🇳 China (CHN)	2	test calls

249 unique pairs, near-zero duplicates. Whoever wrote this was methodical: validate that one full passport comes out cleanly, then move to the next.

Reading the cadence

The timestamps are where a scrape gives itself away. Minute by minute:

11:56   2   ← test phase (incl. the one failure)
11:57   1
11:58   25  ┐
11:59   26  │
12:00   20  │  ~25 req/min, dead regular
  …         │  = one request every ~2.4s
12:07   21  ┘

No human reads visa rules on a 2.4-second metronome for 11 minutes. This is a loop.

The fingerprint

Four signals — and the point isn't nationality, it's that the request parameters themselves leaked the intent:

Handle: visadb_scraper. It signed its own work.
Email: throwaway @temp.com. No intention of receiving anything.
Languages: en + zh, on a product with no Chinese-market surface yet.
Error signature: the very first call (CHN→THA, in Chinese, 11:56:45) failed, then everything ran clean. Classic "calibrating the script" tell.

The math

250 records is 0.6% of the base. At 25 req/min, a full dump would've taken ~26 hours. This wasn't a dump — it was a feasibility test. They proved a whole passport comes out easily, then stopped, nowhere near the 3,000/month free-tier ceiling.

What I couldn't see

I blocked the key (active=false) and the sweep stopped. But my request logs didn't capture the source IP — so I could block the key, not the person. Re-signup costs nothing.

That gap is the real lesson, and it's the subject of the next two posts: rate limits are a cost control, not a security control — and if your logs can't see the network, you can't defend at it.

If you're shipping a data product: assume the first person who finds it valuable will be the first person who tries to copy it. Instrument for that on day one.

Building a Chrome Extension That Shows Visa Requirements Before You Book

Mathis Higuinen — Tue, 16 Jun 2026 04:14:31 +0000

description: How Orizn brings visa requirements directly into Google Flights, Kayak, Skyscanner, and other travel booking flows.
tags: traveltech, chromeextension, startup, buildinpublic

Booking a flight is exciting.

Until one question suddenly appears:

Can I actually enter this country?

That is where the friction starts.

You open Google Flights.
You compare prices, dates, airlines, routes, layovers.

Then you leave the booking flow.

One tab for the flight.
One tab for visa requirements.
One tab for official government sources.
One tab for travel blogs.
Maybe one more tab for Reddit, just to be sure.

And after 20 minutes, you are still not completely confident.

That exact pain is why we built the Orizn Chrome Extension.

👉 extension.orizn.app

The problem

Visa information exists.

But it rarely appears at the moment when travelers need it most.

Most people discover visa rules too late:

after finding a cheap flight
after planning an itinerary
after booking accommodation
sometimes even after buying the ticket

That does not make sense.

Visa requirements should not be an afterthought.

They should appear exactly where the travel decision is being made.

The idea behind Orizn Extension

While traveling, I kept seeing the same pattern again and again.

People were not only asking:

“Where should I go?”

They were also asking:

The answer depends on the passport, the destination, the length of stay, and sometimes the type of entry authorization required.

But travel platforms usually focus on flights, prices, hotels, and availability.

The visa layer is missing.

So we built Orizn Extension to bring that layer directly into the booking experience.

How it works

“Where can I actually go with my passport?”

The extension runs in the background while you browse travel websites such as:

Google Flights
Kayak
Skyscanner
and 30+ other travel platforms

You set your passport once.

Then, when you search for a destination, Orizn instantly shows useful entry information before you book.

For example:

whether you need a visa
how long you can stay visa-free
key travel requirements
useful destination context
important information to check before confirming your trip

No extra tabs.
No unnecessary confusion.
No last-minute surprise.

Just the right information, at the right moment.

Why a Chrome extension?

We could have built only a standalone visa checker.

Actually, we already built the infrastructure behind that.

I wrote about it here:

Building a multilingual API serving 39,585 visa pairs in 15 languages

That API is the foundation.

But the extension solves a different problem.

A visa checker answers a question when the user decides to search for it.

A browser extension answers the question before the user forgets to ask it.

That difference matters.

Because when someone is booking a trip, they are already focused on:

price
dates
destination
luggage
layovers
timing
availability

Visa rules are critical, but they are not always top of mind.

So instead of asking travelers to change their behavior, we decided to meet them where they already are.

Inside the booking flow.

The product experience

The goal was to make the extension feel invisible until it becomes useful.

The user should not have to open a dashboard every time.

They should not have to manually search every destination.

They should not have to copy and paste country names into another tool.

The flow is simple:

Install the extension
Select your passport
Browse travel websites normally
Get visa and destination context when it matters

That is it.

The extension becomes a small decision layer on top of existing travel platforms.

Not another travel app to manage.

Not another tab to keep open.

Just a contextual assistant for international travel decisions.

The bigger vision

Orizn is not only a Chrome extension.

The extension is one part of a larger travel infrastructure ecosystem.

The idea is to build tools that make travel planning clearer, safer, and more intelligent.

That includes:

visa data
travel APIs
browser tools
destination intelligence
developer SDKs
AI agent integrations
multilingual travel infrastructure

The extension is the consumer-facing layer.

The API is the infrastructure layer.

Together, they make visa information available both to travelers and to developers building travel products.

Why this matters

International travel is becoming more complex.

Visa-free access changes.
Electronic travel authorizations are expanding.
Border policies evolve.
Some countries change entry rules quickly.
Travelers often rely on outdated blogs or fragmented information.

That creates risk.

Not just inconvenience.

A traveler can book the perfect flight and still be denied boarding if they missed an entry requirement.

That is the kind of problem we want to reduce.

Not by replacing official sources, but by making important information easier to notice earlier in the decision process.

What we are building next

The current version focuses on surfacing visa and destination context while browsing travel websites.

Next, we want to improve:

more travel website coverage
better destination detection
richer country context
clearer requirement explanations
smoother onboarding
deeper integration with the Orizn Visa API
more personalized travel recommendations based on passport and destination

The long-term goal is simple:

When you are about to book a trip, Orizn should help you understand if that trip is actually possible for your passport.

Final thought

Booking a flight should feel exciting.

Not uncertain.

Visa requirements should not be discovered after the booking.

They should appear before the decision is made.

That is why we built the Orizn Chrome Extension.

👉 Try Orizn Extension

If you are building in travel tech, browser extensions, APIs, or AI agents, I would love to connect and share more about the infrastructure behind Orizn.

Building a multilingual API serving 39,585 visa pairs in 15 languages

Mathis Higuinen — Tue, 26 May 2026 23:34:53 +0000

How we structured a visa requirements database across 15 languages with ISO standardization, caching layers, and translation pipelines.

Most travel APIs return data in English. That's fine if your users are American or British. It's useless if they're Japanese, Thai, Arabic-speaking, or any of the 5.5 billion people whose first language isn't English.

When a Vietnamese traveler looks up visa requirements for France, they need the answer in Vietnamese — not just the visa type, but the required documents list, the application process, the embassy information, the travel tips. Translating "Valid passport with 6 months minimum validity" into 15 languages isn't a string replacement. It's a content localization problem at scale.

The Orizn Visa API serves 39,585 passport-destination pairs in 15 languages: English, French, Spanish, Portuguese, German, Japanese, Korean, Chinese, Russian, Italian, Arabic, Hindi, Thai, Vietnamese, and Filipino. Here's how the system is structured.

Why these 15 languages

Not random. These 15 cover approximately 75% of the world's internet users by primary language:

English — lingua franca, baseline
Chinese — 1.1B speakers, China's visa-free program expanding rapidly
Spanish — 550M speakers, Latin America is a growing travel market
Hindi — 600M speakers, Indian passport holders are one of the most visa-restricted populations
Arabic — 370M speakers, Gulf states have some of the fastest-growing passports
Portuguese — 260M speakers, Brazil alone has 210M people
French — 280M speakers, major passport in Africa and Europe
Japanese, Korean — high-value travel markets, strong outbound tourism
Russian — 250M speakers, complex visa landscape post-2022
German, Italian — core EU passports
Thai, Vietnamese, Filipino — Southeast Asia, where digital nomads concentrate

Each language isn't just a translation — it's a market. A Thai translation means Thai travel bloggers can embed our widgets and Thai developers can build apps with localized visa data.

Data architecture

The core data model is simple:

visa_pair {
  passport:     ISO 3166-1 alpha-3  (e.g. "FRA")
  destination:  ISO 3166-1 alpha-3  (e.g. "JPN")
  requirement:  enum                (visa_free | visa_required | e_visa |
                                     visa_on_arrival | eta | no_admission)
  visa_free_days: integer | null
  verified:     boolean
  source_url:   string
  last_updated: timestamp
}

199 passports × 199 destinations = 39,601 theoretical pairs. Some pairs are self-referential (you don't need a visa to visit your own country), bringing the actual count to 39,585.

Each pair has a base record in English. Translations are stored separately:

visa_translation {
  passport:     ISO3
  destination:  ISO3
  lang:         enum (15 values)
  description:  text
  documents:    text[]
  process:      text[]
  tips:         text[]
}

39,585 pairs × 15 languages = 593,775 translation records. That's the real scale of the system.

The translation pipeline

Raw visa data comes from 136 government portals. Most publish in their national language plus English. Some only publish in their national language.

The pipeline has 5 stages:

1. Extraction — Pull structured visa rules from government sources. This is the hardest part. Every government formats their visa information differently. Some have clean REST APIs. Most have PDF documents or HTML pages with inconsistent formatting.

2. Normalization — Map to the 6 standardized requirement types. A government might say "no visa needed for stays under 90 days" — that maps to visa_free with visa_free_days: 90. Another might say "electronic authorization required prior to travel" — that's eta. The mapping isn't always obvious and edge cases are everywhere.

3. English baseline — Generate the English version with all fields: description, documents_required, process, tips, country_info. This is the canonical record that everything else derives from.

4. Translation — Generate the 14 other language versions. This isn't word-for-word translation. Document names, process steps, and tips need to be culturally adapted. "Apply at the embassy" in Japanese includes the Japanese name of the embassy and Japanese-language application forms. "Proof of sufficient funds" in Arabic needs to reflect local banking norms.

5. Verification — Cross-check against at least 2 independent sources per pair. The verified flag indicates whether the data has been confirmed. Unverified pairs are still returned but flagged — better to have data with a caveat than no data at all.

Caching strategy

With 593K+ records and 15 language variants, caching is critical:

Request flow:
Client → API Gateway → Cache (Redis) → Database

Cache key pattern: visa:{passport}:{destination}:{lang}

The TTL strategy is split by volatility:

24 hours for stable pairs — visa types don't change hourly. A visa_free pair that's been stable for 3 years doesn't need real-time freshness.
1 hour for recently changed pairs — if Thailand just modified its policy, the cache needs to reflect that quickly.
No cache for the /changes endpoint — it queries the diff table directly. When someone asks "what changed this week?", they need the latest data, not a cached snapshot.

The /check endpoint (quick check, no documents) is cached aggressively — it returns 5 fields. The /visa endpoint (full details with documents, process, tips) has shorter TTLs because embassies can update document requirements at any time.

ISO standardization decisions

We use ISO 3166-1 alpha-3 exclusively. Not alpha-2 (FR, JP), not country names (France, Japan), not IATA codes (CDG, NRT). Three reasons:

Unambiguous — alpha-3 has no collisions across all 199 countries
Universal — same codes work regardless of language (a Japanese developer sends FRA, not フランス)
Machine-readable — 3 uppercase ASCII characters, trivially validatable with a regex

The API auto-uppercases inputs (fra → FRA) and returns clear error messages for invalid codes:

{
  "error": "\"passport\" value \"JP\" is not a valid ISO 3166-1 alpha-3 code. Did you mean \"JPN\"?"
}

This matters especially for MCP and agent usage where the LLM might send lowercase or alpha-2 codes. A clear error message lets the agent self-correct and retry.

What I'd do differently

Start with fewer languages. Launching with 15 simultaneously was ambitious. Starting with 5 (English, Spanish, French, Chinese, Arabic) and adding based on demand would have been faster and let us focus quality on the highest-impact languages first.

Invest in government source monitoring earlier. The hardest operational challenge isn't translation — it's knowing when a government changes its visa policy. Thailand's 60→30 day rollback happened via a cabinet resolution. That's not an RSS feed. Building automated monitoring for 136 government portals is an ongoing project.

Build the diff system from day one. We added the /changes endpoint later. If we'd built temporal versioning into the data model from the start (valid_from, valid_to on every record), the change detection and audit trail features would have been trivial instead of retrofitted.

Try the API

The multilingual response in action:

# English (free, no API key)
curl "https://visa.orizn.app/api/v1/visa/check?passport=JPN&destination=FRA"

# Japanese (needs free API key)
curl -H "x-api-key: YOUR_KEY" \
  "https://visa.orizn.app/api/v1/visa?passport=JPN&destination=FRA&lang=ja"

# Arabic
curl -H "x-api-key: YOUR_KEY" \
  "https://visa.orizn.app/api/v1/visa?passport=JPN&destination=FRA&lang=ar"

Quick checks are free, no API key needed. Full details in 15 languages with a free key (3,000 req/month) from visa.orizn.app.

SDKs: npm install orizn · pip install orizn · cargo add orizn

Source: github.com/MattJeff/orizn-visa-api

Building an MCP Server for Visa Requirements in TypeScript

Mathis Higuinen — Tue, 26 May 2026 15:15:10 +0000

What is MCP, and why should you care?

The Model Context Protocol (MCP) is an open standard created by Anthropic that lets AI agents connect to external tools and data sources through a unified interface. Think of it as USB-C for AI: one protocol, any agent. Instead of building custom integrations for Claude, GPT, Gemini, and every other model, you build one MCP server and every compatible agent can use it.

MCP defines a simple contract. Your server exposes tools (functions the AI can call) and resources (data the AI can read). The agent discovers what's available, reads the descriptions, and decides when to use them. The transport layer is pluggable -- stdio for local tools, SSE or HTTP for remote ones.

The protocol is gaining traction fast. Claude Desktop, Cursor, Windsurf, and dozens of other clients already support it. If you have an API that AI agents should be able to use, wrapping it in MCP is one of the highest-leverage things you can do right now.

Why visa requirements are perfect for MCP

Here's a problem every travel-focused AI agent has: visa requirements. Ask an LLM whether a Brazilian passport holder needs a visa for Japan, and you'll get an answer -- but it might be wrong. Models rely on training data that's months or years old, and visa policies change constantly. Thailand just launched a new 60-day visa exemption. Turkey updated its e-visa rules. The model doesn't know.

Visa data is structured, query-driven, and time-sensitive. It's exactly the kind of information that should come from a live API, not from parametric memory. An MCP server bridges that gap: the agent recognizes a visa question, calls the tool, and gets current data from a real database.

That's what we built with the Orizn Visa MCP Server -- a TypeScript MCP server backed by an API covering 39,585 passport-destination pairs in 15 languages.

Architecture overview

The stack is deliberately minimal:

Runtime: Node.js 18+
Language: TypeScript
MCP SDK: @modelcontextprotocol/sdk (v1.12+)
Transport: stdio (runs locally alongside the AI client)
Backend: Orizn Visa API at https://visa.orizn.app/api/v1/visa

The server exposes 5 tools and 2 resources:

Tools	Description
`check_visa_requirement`	Full visa details for a passport-destination pair
`quick_visa_check`	Fast yes/no check (free, no API key)
`get_all_destinations`	All destinations for one passport at once
`get_visa_changes`	Recent visa policy updates
`get_coverage_stats`	Database coverage statistics

Resources	Description
`visa://supported-languages`	The 15 supported language codes
`visa://country-codes`	All 199 ISO3 country codes the API accepts

Code walkthrough

Server initialization

MCP servers start with a Server instance and a transport. We use StdioServerTransport, which communicates over stdin/stdout -- the standard for local MCP servers:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "orizn-visa", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

const transport = new StdioServerTransport();
await server.connect(transport);

You register capabilities upfront -- tools and resources -- so the client knows what to expect.

Defining tools

Tools are defined with a name, description, and JSON Schema for inputs. Here's the core visa check tool:

{
  name: "check_visa_requirement",
  description:
    "Check visa requirements between any two countries. Returns visa type " +
    "(visa-free, e-visa, visa required, etc.), allowed stay duration, " +
    "required documents, step-by-step application process, and travel tips. " +
    "Covers 39,585 passport-destination pairs in 15 languages. " +
    "Use this tool when the user asks about visa rules, entry requirements, " +
    "or whether they need a visa to visit a country.",
  inputSchema: {
    type: "object",
    properties: {
      passport: {
        type: "string",
        description: "ISO 3166-1 alpha-3 code of the passport (e.g. 'FRA').",
      },
      destination: {
        type: "string",
        description: "ISO 3166-1 alpha-3 code of the destination (e.g. 'JPN').",
      },
      lang: {
        type: "string",
        description: "Language code for the response. Defaults to 'en'.",
      },
    },
    required: ["passport", "destination"],
  },
}

The tool handler validates inputs and calls the API:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args = {} } = request.params;

  switch (name) {
    case "check_visa_requirement": {
      const passport = validateISO3(args.passport, "passport");
      const destination = validateISO3(args.destination, "destination");
      const lang = validateLang(args.lang);
      const result = await apiFetch("", { passport, destination, lang }, apiKey, true);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
    // ... other tools
  }
});

Resources

Resources let the agent look up reference data without burning an API call. We expose two static resources -- supported languages and valid country codes:

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  switch (request.params.uri) {
    case "visa://supported-languages":
      return {
        contents: [{
          uri: request.params.uri,
          mimeType: "application/json",
          text: JSON.stringify(SUPPORTED_LANGUAGES_RESOURCE, null, 2),
        }],
      };
    case "visa://country-codes":
      return {
        contents: [{
          uri: request.params.uri,
          mimeType: "application/json",
          text: JSON.stringify(COUNTRY_CODES_RESOURCE, null, 2),
        }],
      };
  }
});

This way, when the agent isn't sure of a country code, it can check the resource first instead of guessing.

API client with retry logic

The API client handles timeouts, retries on 5xx errors, and fails fast on 4xx:

async function apiFetch(path: string, params: Record<string, string>,
                        apiKey: string | undefined, requiresKey: boolean): Promise<unknown> {
  let lastError: Error | undefined;

  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);

    try {
      const response = await fetch(url.toString(), {
        method: "GET", headers, signal: controller.signal,
      });
      clearTimeout(timeout);

      if (response.ok) return await response.json();

      // Don't retry client errors -- the request itself is wrong
      if (response.status >= 400 && response.status < 500) {
        throw new McpError(ErrorCode.InvalidRequest,
          `API returned ${response.status}: ${await response.text()}`);
      }

      // 5xx: retry
      lastError = new Error(`API returned ${response.status}`);
    } catch (err) {
      clearTimeout(timeout);
      if (err instanceof McpError) throw err;
      lastError = err instanceof Error ? err : new Error(String(err));
    }
  }

  throw new McpError(ErrorCode.InternalError,
    `API request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message}`);
}

The distinction between 4xx and 5xx is important. A 400 means the agent sent bad parameters -- retrying won't help. A 503 means the server hiccupped -- retrying might.

ISO3 validation

Country codes are validated against a hardcoded set of 199 codes before hitting the API. This catches the most common error pattern (the LLM sends "JP" instead of "JPN") at the MCP layer with a clear error message, rather than letting it propagate as a cryptic API error:

function validateISO3(code: unknown, paramName: string): string {
  const upper = (code as string).toUpperCase();
  if (!ISO3_COUNTRY_CODES.has(upper)) {
    throw new McpError(ErrorCode.InvalidParams,
      `"${paramName}" value "${code}" is not a valid ISO 3166-1 alpha-3 country code.`);
  }
  return upper;
}

Key decisions and lessons learned

Tool descriptions are your most important code. The LLM reads them to decide when to invoke your tool. Vague descriptions mean the agent won't call your tool when it should. We explicitly state what each tool returns, what it covers (39,585 pairs, 15 languages), and when to use it versus alternatives. This isn't documentation -- it's prompt engineering.

stdout is sacred. In stdio transport, stdout carries MCP protocol messages. If you console.log() anything, you'll corrupt the protocol stream and crash the connection. All our logging goes to stderr via process.stderr.write(). This is the #1 mistake people make when building their first MCP server.

Free tier drives adoption. The quick_visa_check and get_coverage_stats tools work without an API key. This means anyone can npx orizn-visa-mcp and immediately test it. Zero friction. If they need full details, they add a key. But the first experience is instant.

Validate before you fetch. Catching "FR" vs "FRA" at the validation layer gives the agent a clear, actionable error ("not a valid ISO 3166-1 alpha-3 code") instead of a generic API 400. The agent can self-correct and retry with the right format.

Publishing and distribution

Building the server is half the work. Getting it in front of developers is the other half.

npm publish -- This enables npx orizn-visa-mcp, the fastest path from discovery to running server. Set the bin field in package.json and add the shebang (#!/usr/bin/env node) to your entry point.
MCP registries -- Submit to Smithery, mcp.so, and Glama. These are where developers browse for MCP servers. A smithery.yaml config file handles Smithery's hosted deployment.
README as marketing -- Your README is your landing page. Include a clear one-liner, a feature table, installation instructions for every major client (Claude Desktop, Cursor, VS Code), and example outputs. Most developers decide whether to try your server in 30 seconds of scanning the README.

Try it

The server is open source and ready to use:

GitHub: github.com/MattJeff/orizn-mcp-server
npm: npmjs.com/package/orizn-visa-mcp
Run it: npx orizn-visa-mcp
API docs: visa.orizn.app

If you're building an AI agent that touches travel, immigration, or international logistics, plug this in and your agent gets reliable visa data instead of hallucinated guesses. And if you're building your own MCP server -- steal the patterns. The protocol is simple, the SDK is solid, and the ecosystem is growing fast.