Meridian logo
Meridian Online now

API reference

Meridian API.
One reference, all surfaces.

Visa rules, applications, vault, and Computer-driven submissions for any AI assistant or backend. Anonymous public tier; OAuth for user-scoped tools. Wire endpoint over MCP.

OpenAPI 3.1 specJump to Requirements API

Conventions

Universal across every API

These apply to every tool on the MCP server. Each API section below adds its own contracts on top.

Authentication

The public tier is anonymous. No key, token, or account required for requirements_lookup and requirements_evaluate.

User-scoped tools prompt for OAuth on first call. Your client handles the flow automatically when it sees an authentication_required envelope. Tool tiers live on the install page.

Versioning

Stripe-shaped request-level versioning. Pin with the Meridian-Api-Version header. The current version is 2026-05-15. Missing or unknown values fall forward to the latest supported version; the server always echoes the applied version back in the response header.

bash
curl https://usemeridian.app/mcp \
  -H "Content-Type: application/json" \
  -H "Meridian-Api-Version: 2026-05-15" \
  -d '...'

MCP protocol version: 2025-11-25. Full supported list at GET /.well-known/mcp/server.

Pagination

List responses are cursor-paginated. Pass limit (1 to 100, default 25). When the response carries next_cursor, thread it back as cursor. Cursors are opaque; do not construct or modify them. An absent or null next_cursor means you have reached the end.

json
{
  "structuredContent": {
    "object": "list",
    "data": [ ... ],
    "next_cursor": "cur_eyJwYWdlIjoyfQ",
    "has_more": true
  }
}

Errors

Every error returns a structured envelope. type is enum-constrained for programmatic dispatch; code is a stable string for fine-grained branching within a type.

json
{
  "object": "error",
  "type": "validation_error",
  "code": "invalid_passport_iso",
  "message": "passport_iso 'XX' is not a recognised ISO-3166 alpha-2 code.",
  "hint": "Pass a two-letter country code such as 'NG' or 'GB'."
}
  • validation_errorYour inputs failed schema or business-rule validation. Fix the request.
  • not_foundThe corridor or resource is unknown to Meridian. Surface the gap to the user.
  • authentication_requiredA user-scoped tool was called without a token. Your client should run the OAuth flow.
  • authorizationYour token is valid but not allowed to access this resource.
  • invalid_stateThe resource exists but is in a state that does not allow this action.
  • invalid_requestThe JSON-RPC envelope is malformed.
  • internalSomething went wrong on our side. Retry with backoff; if persistent, contact support.

APIs

Tools by resource

Meridian's MCP catalog groups tools by resource. Requirements is the only API fully documented here today; Applications and Vault round-trip to the install page until those sections fill.

Requirements API

Visa rules for any corridor: verdict, fee, processing time window, document checklist, process steps, and verified embassy sources. Anonymous public tier.

requirements_lookup

POST https://usemeridian.app/mcp

Parameters
passport_isostringrequired

ISO-3166 alpha-2 code of the traveler's passport country (NG, GH, IN, KE, etc). Case-insensitive.

destination_isostringrequired

ISO-3166 alpha-2 code of the destination country (GB, SE, US, AE, etc). Case-insensitive.

visa_typestringoptional

One of: tourism, business, family, study, medical, transit. Defaults to tourism.

residence_isostringoptional

ISO-3166 alpha-2 code of the traveler's country of long-term residence, when different from passport. Triggers reciprocity rules (Schengen permits, EU LTR, US LPR, Canada PR).

cursorstringoptional

Opaque cursor returned by a prior page. Forward-only; never construct one by hand.

limitintegeroptional

Page size between 1 and 100. Defaults to 25.

Request
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "requirements_lookup",
    "arguments": {
      "passport_iso": "NG",
      "destination_iso": "GB",
      "visa_type": "tourism"
    }
  }
}
Response
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "structuredContent": {
      "object": "requirements.lookup",
      "data": {
        "route": {
          "passport_iso": "NG",
          "destination_iso": "GB",
          "visa_type": "tourism"
        },
        "verdict": "embassy",
        "fee": { "amount": 127, "currency": "GBP" },
        "processing_time": { "min_days": 15, "max_days": 21 },
        "documents": [
          { "name": "Passport", "notes": "Valid for 6 months past return; 1 blank page" },
          { "name": "Bank statement", "notes": "Last 3 months, stamped" },
          { "name": "Photo", "notes": "45x45mm, white background" }
        ],
        "process": [
          { "step": 1, "label": "Apply online", "url": "https://www.gov.uk/standard-visitor-visa" },
          { "step": 2, "label": "Book biometrics", "url": "https://www.vfsglobal.co.uk/" },
          { "step": 3, "label": "Attend appointment" }
        ],
        "sources": [
          { "type": "official", "url": "https://www.gov.uk/standard-visitor-visa", "verified": true }
        ],
        "schema_version": "2026-05-15"
      },
      "id": "req_NG_GB_tourism",
      "updated_at": "2026-05-12T08:00:00Z",
      "schema_version": "2026-05-15"
    }
  }
}

Note. Every response carries both content (legacy JSON-stringified blob for older MCP clients) and structuredContent (parsed object, MCP 2025-11-25). Prefer structuredContent in new code.

Code samples

curl

bash
curl -X POST https://usemeridian.app/mcp \
  -H "Content-Type: application/json" \
  -H "Meridian-Api-Version: 2026-05-15" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "requirements_lookup",
      "arguments": {
        "passport_iso": "NG",
        "destination_iso": "GB",
        "visa_type": "tourism"
      }
    }
  }'

node

javascript
const res = await fetch("https://usemeridian.app/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Meridian-Api-Version": "2026-05-15"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "requirements_lookup",
      arguments: {
        passport_iso: "NG",
        destination_iso: "GB",
        visa_type: "tourism"
      }
    }
  })
});
const { result } = await res.json();
console.log(result.structuredContent.data);

python

python
import requests

res = requests.post(
    "https://usemeridian.app/mcp",
    headers={
        "Content-Type": "application/json",
        "Meridian-Api-Version": "2026-05-15",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "requirements_lookup",
            "arguments": {
                "passport_iso": "NG",
                "destination_iso": "GB",
                "visa_type": "tourism",
            },
        },
    },
)
print(res.json()["result"]["structuredContent"]["data"])

Applications API

Create, evaluate, and submit visa applications. User-scoped; requires OAuth. Tools and request shapes documented on the install page until this section expands.

Vault API

Identity store and document upload. User-scoped; requires OAuth. Tools and request shapes documented on the install page until this section expands.

Install

Three surfaces, one backend

Read the contract.
Then wire it in.

Drop the MCP server URL into any client, install the agent skill for opinionated orchestration, or hit the same surface from your terminal.

Install the MCP serverUse the CLIInstall the agent skill