Voyagier Cli MCP Server

@voyagier/cli

Search flights, book activities, manage trip plans — from your terminal. Everything syncs to voyagier.com.

npm install -g @voyagier/cli
voyagier auth set-token <your-token>
voyagier doctor   # confirm auth + schema reachability

No install permissions (sandboxed agent, CI)? Every command works zero-install via npx:

VOYAGIER_TOKEN=<your-token> npx @voyagier/cli doctor --json

Quick Start

A trip plan is a goal graph: the plan ships with goals (flights, hotel, dates, destination, travellers) and you compose the trip by searching against those goals and selecting options. Searches are asynchronous — a search creates a selection, and options arrive shortly after, so you poll for them.

# 1) Resolve a client (idempotent by email)
voyagier clients upsert --email "smith@example.com" --name "Smith Family" \
  --type Individual --json

# 2) Scaffold a plan (creates the plan + default goal graph; optionally adds
#    travellers if you pass --travellers)
voyagier plan-trip --client "Smith Family" --title "Smith — Tokyo" --json
# Returns a scaffold summary: { ok, tripPlanId, title, travellerIds, scaffolded,
# note, url, nextSteps } — the nextSteps are the compose commands for this plan.

# 3) Add a traveller
voyagier travellers add --plan <PLAN_ID> --first John --last Smith \
  --type Adult --json

# 4) Search flights → poll for options → select
voyagier search flights --plan <PLAN_ID> --from JFK --to NRT \
  --date 2026-09-15 --return 2026-09-22 --json
# Returns a selectionId. Options are fetched asynchronously:
voyagier selection-options <SELECTION_ID> --wait --json
voyagier select --selection-id <SELECTION_ID> --option-id <OPTION_ID> --wait --json

# 5) Search a hotel → poll → select
voyagier search hotels --plan <PLAN_ID> --location Tokyo \
  --checkin 2026-09-15 --checkout 2026-09-22 --json
voyagier selection-options <SELECTION_ID> --wait --json
voyagier select --selection-id <SELECTION_ID> --option-id <OPTION_ID> --json

# 6) Inspect readiness at any time — one call: what's blocked, what's next
voyagier plan-status <PLAN_ID> --json

# 7) Pre-flight (dry-run: blockers + chargeable subtotal), then checkout (price gate required)
voyagier book <PLAN_ID> --dry-run --json                   # preview: blockers + chargeable subtotal; no gate needed
voyagier book <PLAN_ID> --expect-total <subtotal> --json   # checkout only at that exact price
voyagier book <PLAN_ID> --validate --expect-total <subtotal> --json  # strict: also abort if ANY item is non-bookable

What's Bookable

The cart materializes only bookable, fare/room-level options — the per-item isBookable flag is the live truth. Always run voyagier book <planId> --dry-run first for pre-flight checks (blockers + chargeable subtotal, no gate needed); --validate is a strictness modifier on the real booking that aborts if any item is non-bookable. A real checkout requires a price gate (--expect-total or --max-total) against the chargeable subtotal, and the checkout is always pinned to that gated set via itemIds — --types / --only-bookable narrow it server-side. Note: unpaid (Pending) checkout sessions are not visible to the CLI, so never retry a successful book. Cart items sourced from live-rate suppliers may report source: "OTHER" — that's normal, not an error.

Commands

Most data-bearing commands accept --json for structured output (notable exceptions: chat, telemetry, several auth subcommands). Use --plan <id> on select to prevent cross-plan state corruption when running parallel workflows.

For AI Agents

voyagier agent-docs    # full reference (AGENT.md)
npx @voyagier/cli agent-docs   # zero-install variant

Or read AGENT.md directly. It covers the goal-graph compose model, async option fetch, per-command JSON shapes, the error code table, and the bookability matrix.

MCP server

The CLI ships an MCP stdio server that exposes the agent surface as tools, for hosts that speak the Model Context Protocol (Claude Desktop, Cursor, etc.):

voyagier mcp          # run the stdio server (JSON-RPC on stdout)

It's a thin adapter: each tool call self-spawns the CLI as a subprocess with --json (the one exception is agent_docs, which runs without it), so the tools inherit the CLI's uniform error codes and price-gated checkout — zero behaviour drift. The MCP layer normalises every result into ONE canonical envelope: on success { ok: true, data: <object>, planContext? } (agent_docs markdown arrives as data.content), and on failure { ok: false, error: { code, message, details? } } with isError: true. Authentication flows through the environment (VOYAGIER_TOKEN / VOYAGIER_API_URL); the MCP layer never sees your token.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "voyagier": {
      "command": "npx",
      "args": ["-y", "@voyagier/cli", "mcp"],
      "env": { "VOYAGIER_TOKEN": "voy_pat_xxxxx" }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "voyagier": {
      "command": "npx",
      "args": ["-y", "@voyagier/cli", "mcp"],
      "env": { "VOYAGIER_TOKEN": "voy_pat_xxxxx" }
    }
  }
}

Tools

send is intentionally excluded from the MCP surface. voyagier send emails a real client an invite link and is not idempotent — every call re-emails. That side effect is too consequential to expose behind an autonomous tool call; use the CLI directly (voyagier send <planId> --yes) when you mean it. The MCP close path is quote → book.

book cannot be retried safely. Unpaid Stripe sessions are invisible to the pre-flight, so a retry mints a duplicate payable link. Treat a successful book as terminal.

Environment Variables

How It Works

Thin client over Voyagier's GraphQL API — the same API the web app uses. Everything syncs both ways. A plan is a goal graph; searching composes selections against goals, and air, accommodation, activity, and places suppliers are all surfaced through one unified selection model.

Getting Access

Voyagier is currently invite-based. Advisors and agent builders can request access at voyagier.com — once invited, you can self-serve a personal access token from your account.

Tip: prefer voyagier login (interactive prompt) over voyagier auth set-token <token> — it keeps your token out of shell history. For scripts, use the VOYAGIER_TOKEN env var.

License

Apache-2.0 — Copyright 2026 Voyagier, Inc. Use of Voyagier services through the CLI is subject to the Voyagier Terms of Service. "Voyagier" and the Voyagier logo are trademarks of Voyagier, Inc.; the Apache-2.0 license does not grant trademark rights.