Octo

OCTO MCP Server — unofficial demo

⚠️ Unofficial · not affiliated with, or endorsed by, OCTO. An independent demo of how AI agents could use the open OCTO standard for tours, activities & attractions. It books against mock suppliers (and, optionally, a Ventrata test supplier). No real bookings, no real charges.

Give your AI the power to book a tour. This is a tiny Model Context Protocol server. Add it to Claude, Cursor, Windsurf, or any MCP client and your assistant can discover and book in-destination experiences across every connected OCTO supplier through one server — with a human approving before anything is charged.

It answers a strategic question for OCTO: as travelers start asking their AI assistants to book things, who are the rails between the agent and the supplier?

---

⚡ Add it to your AI (60 seconds)

Everything below uses one stable command — no install, no dead paths: npx -y -p github:MyTrip-ai/octo-mcp-server octo-mcp-server-stdio

Easiest — a guided wizard that detects your client and configures it for you:

npx github:MyTrip-ai/octo-mcp-server connect

Or copy-paste for your client:

Client	How
Claude Code	claude mcp add octo -s user -- npx -y -p github:MyTrip-ai/octo-mcp-server octo-mcp-server-stdio
Claude Desktop	Settings → Developer → Edit Config → add the octo block below, then fully quit & reopen
Cursor	add the block below to ~/.cursor/mcp.json
Windsurf	add the block below to ~/.codeium/windsurf/mcp_config.json
VS Code (Copilot/agent)	Command Palette → “MCP: Add Server” → Command (stdio), or paste into your user mcp.json (uses "servers" + "type")
ChatGPT	(not recommened, complicated setup for MCPs...) add the hosted URL https://octo.mytrip.ai/mcp (Settings → Connectors) — see Hosted endpoint

{
  "mcpServers": {
    "octo": {
      "command": "npx",
      "args": ["-y", "-p", "github:MyTrip-ai/octo-mcp-server", "octo-mcp-server-stdio"]
    }
  }
}

npx github:MyTrip-ai/octo-mcp-server connect --print prints the exact config for every client. First launch fetches + builds (a few seconds); after that it's cached.

Ran the command and it printed one line then “froze”? That's correct — you're not meant to run it by hand. A stdio MCP server prints its startup line and then waits silently for your AI client to speak the protocol on stdin. Your client (Claude, Cursor, …) launches it for you. To prove it answers, pipe it a request:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' \
  | npx -y -p github:MyTrip-ai/octo-mcp-server octo-mcp-server-stdio

Then tell your AI:

“Use the octo tools to book me a Galápagos snorkel tour for Saturday.”

It'll discover → check availability → hold, then stop and ask you to approve before confirming. That human-in-the-loop gate is the whole point.

🧭 Or try it without installing

npx github:MyTrip-ai/octo-mcp-server          # a chooser: add-to-AI · guided demo · the pitch
npx github:MyTrip-ai/octo-mcp-server demo     # the 90-second narrated pitch

Prefer to read it? media/octo-demo.txt is the transcript, or npx asciinema play media/octo-demo.cast.

Why this matters for OCTO

1. A new distribution channel. When travelers ask their AI to book experiences, OCTO can be the rails between agent and supplier.
2. Build once, reach every supplier. A single MCP server fronts all OCTO suppliers — the same standardization that powers today's resellers powers AI agents tomorrow. Add another OCTO supplier (Bókun, Ventrata, …) and it appears with zero new code.
3. OCTO can lead this. A canonical "agent-ready" profile — an octo/mcp or octo/ai-content capability — would let suppliers advertise AI-readiness and put OCTO ahead of the curve. (An open question this demo is meant to start, not settle.)

How it works (the design that makes it safe)

Deliberately not a 1:1 wrapper of the OCTO REST API — that's a footgun for LLMs. Full rationale in DESIGN.md. The essentials:

• One server, many suppliers — every supplier sits behind one adapter (mock or live HTTP).
• The model never touches opaque IDs — the OCTO availabilityId and idempotency uuid stay server-side, so an agent can't double-book.
• Money is human-readable — OCTO's integer + currencyPrecision becomes "$180.00 USD".
• Human-in-the-loop on spend — confirm_booking refuses without explicit approval.
• Capabilities + auth negotiated server-side — the model never manages headers or keys.

Use live OCTO inventory (optional)

Set a free Ventrata test key in a git-ignored .env (or the connect wizard / Guided Concierge will offer to take one):

VENTRATA_OCTO_ENDPOINT=https://api.ventrata.com/octo
VENTRATA_OCTO_API_KEY=your-free-test-key
# optional: ANTHROPIC_API_KEY=...  (upgrades the built-in chat brain to Claude)

Get one at https://dashboard.ventrata.com/octo/signup (test supplier "EdinExplore").

🌐 Hosted endpoint (ChatGPT & remote clients)

A live remote (Streamable HTTP) endpoint is already running:

https://octo.mytrip.ai/mcp

Visit https://octo.mytrip.ai in a browser to see it live — an overview page with the tool list and connect instructions. (The /mcp path itself is a protocol endpoint, not a web page, so opening it directly just shows a short "you've reached the wire" note — that's expected; an MCP client talking to it gets all the tools.)

Add it to any MCP client that supports remote servers — e.g. ChatGPT (Settings → Connectors → add a custom connector with that URL; Developer mode may be required), or remote Claude/Cursor. No install needed. Unofficial · mock/test data · no real charges.

Self-host your own: npm run serve (or node dist/serve.js) behind a TLS reverse proxy; set OCTO_ALLOWED_HOSTS=your.host for DNS-rebinding protection. See src/serve.ts.

Architecture

src/
  index.ts          the OCTO MCP server (stdio) — 9 tools, resources, prompts
  octo/             OCTO types + adapter seam (mockAdapter, httpAdapter)
  chat/engine.ts    shared chat engine (deterministic + Claude brains, parsers)
  cli/              the CLI: clients registry · connect · concierge · demo · ui
scripts/            bridge (web chat) + smoke/live/cli/connect/demo tests + make-cast
web/                a browser chat over the same MCP server (npm run bridge)
media/              the recorded demo (.cast + .txt)

Develop & verify

npm install
npm run connect-smoke  # client registry + config writers + handshake (13 checks)
npm run smoke          # MCP server, mock suppliers (12)
npm run live           # real OCTO round-trip via Ventrata (needs a key)
npm run cli-smoke      # guided flow, end to end
npm run demo-smoke     # narrated pitch
npm run cast           # regenerate media/octo-demo.{cast,txt}
npm run bridge         # browser chat at http://localhost:8787

9 Available text triggered tools: 
Tool	Type	What the AI calls it for
list_suppliers	read-only	"What suppliers are available?"
search_products	read-only	"Find Galápagos snorkel tours"
get_product_details	read-only	"Show me the full details + cancellation policy"
check_availability	read-only	"What's available Saturday for 2 adults?" → returns slot handles like slot-3
create_hold	write (idempotent)	"Hold slot-3 for 2 adults" → returns BK-1 + countdown
confirm_booking	destructive	"Confirm BK-1" → refuses without humanApproved=true
cancel_booking	destructive	"Cancel BK-1" → refuses without confirm=true
get_booking	read-only	"What's the status of BK-1?"
list_bookings	read-only	"Show all bookings this session"

License

MIT. A reference artifact for the conversation about AI agents and the OCTO standard. Again: unofficial — not affiliated with OCTO.