We Built an MCP Server for Jamaica Transfers — Here's What We Learned

Why MCP over a REST API?

We already had a REST API powering our website and booking system. So why build an MCP server on top of it?

The answer is distribution. A REST API requires developers to write integration code — HTTP clients, error handling, auth flows, UI. An MCP server lets any AI assistant use your tools natively. The AI handles the UX. You just provide the capabilities.

For a transfer company, this means any Claude user in the world can get a live quote without us building a chatbot, a Slack integration, or a mobile app. The AI assistant is the interface.

Architecture: FastAPI daemon + MCP endpoint

Our stack is straightforward:

• Daemon: Python FastAPI app on Railway, handling all business logic
• Database: Supabase (PostgreSQL) with 36 tables — routes, pricing, fleet, directory listings
• MCP endpoint: POST /mcp using Streamable HTTP transport
• Auth: API key via X-AurumOS-Key header

The MCP endpoint is a thin layer that translates JSON-RPC tool calls into internal API calls. Each tool maps to one or more database queries.

Designing 20 tools

Tool design is the hardest part. Too few tools and the AI cannot do anything useful. Too many and it gets confused about which to call.

We landed on 20 tools across three domains:

Transfers and Booking (7 tools)

get_quote is the star — it accepts origin, destination, and passenger count in natural language. The AI can pass "MBJ", "Montego Bay airport", or "Sangster International" and it resolves correctly. create_booking generates a PayPal invoice link. check_booking_status lets users track existing bookings.

Fleet and Services (3 tools)

get_airports, get_fleet, and get_chauffeur_packages provide reference data the AI needs for context. Without these, it would hallucinate vehicle types or make up package names.

Tourist Directory (10 tools)

Our directory has 4,100+ businesses across Jamaica. The directory tools let business owners submit listings, upload images, check analytics, and upgrade their tier — all through conversation with an AI.

Key design decisions

1. Tool names matter

We use get_quote not transfers.quote. The AI reads tool names to decide which to call. Clear, verb-first names reduce wrong calls.

2. Rich descriptions do the heavy lifting

Each tool has a detailed description telling the AI when and how to use it. For example, get_quote says "MUST be called before stating any price" — this prevents hallucinated pricing.

3. Flexible inputs, structured outputs

get_quote accepts fuzzy destination names ("Sandals Negril", "the resort near seven mile beach") and returns structured JSON with exact pricing, vehicle options, and drive times. The AI handles the fuzzy-to-structured translation.

4. System prompt as guardrail

Our Smithery config includes a system prompt that tells the AI: "Never invent prices or payment URLs. All data must come from tool results." This is critical — without it, the AI will confidently quote prices it made up.

Publishing to Smithery

Smithery is the registry for MCP servers — think npm for AI tools. The submission process:

1. Create a smithery.yaml with server metadata, transport config, and auth details
2. Push to a public GitHub repo
3. Submit via Smithery dashboard
4. Automated checks run (connectivity, tool validation, response times)

We scored 99/100 on first submission. The one-point deduction was a minor metadata field we added later.

Lessons learned

MCP transport on Windows

The standard mcp-remote npm package crashes on Windows with EPIPE errors — log output corrupts the JSON-RPC stream on stdout. We wrote a custom proxy.js that routes all logging to stderr. This is now our recommended setup for Windows users.

Rate limiting is essential

Without rate limits, a single AI conversation can fire dozens of tool calls in seconds. We added per-key rate limiting at the daemon level.

Test with real AI behaviour

Unit tests for individual tools are not enough. You need to test how the AI actually uses the tools in conversation. It will call tools in unexpected orders, pass unexpected parameter formats, and ask for tool combinations you did not anticipate.

Results

The MCP server went live on Smithery on April 9, 2026. It connects to live pricing data, supports all three Jamaica airports (MBJ, KIN, OCJ), and covers every destination on the island.

The entire server is MIT licensed. Fork it, learn from it, build your own.

• Smithery listing (99/100 score)
• Installation guide