How to Give an AI Agent Travel Tools With the Dreamfare MCP Server

The Model Context Protocol is how AI assistants and agents call tools that live outside the model. Dreamfare exposes its travel capabilities as one remote MCP server, so an agent you build, whether in Claude Code, Cursor, a LangGraph pipeline or a plain script, can create and edit real trips, plan itineraries, search stays and activities with live prices, import travel videos and share the result with a traveler's crew.

This guide is the developer walkthrough. The consumer setup for ChatGPT and Claude is on Use Dreamfare in ChatGPT and Claude; the reference page with every tool is at /mcp/tools.

What you are connecting to

• Endpoint: https://api.dreamfare.app/mcp
• Transport: Streamable HTTP, stateless. Every POST is a complete JSON-RPC exchange and the response is JSON. There is no SSE stream to hold open and no session id to carry, so any client and any replica can call it.
• Registry name: app.dreamfare/mcp in the official MCP Registry, which is how clients that browse the registry find it.
• Auth: OAuth 2.1 with PKCE and dynamic client registration. Tokens are scoped to the traveler who signed in.
• Rate limit: 120 requests per minute per client.

Three protocol methods answer without a token: initialize, ping and tools/list. That is deliberate. A registry, a scanner or your own build script can read the catalog before any user has connected. Everything that touches an account, above all tools/call, needs the bearer token.

Read the catalog first

Before writing any code, look at what the server offers:

curl -X POST https://api.dreamfare.app/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The reply lists every tool with its name, a title, a description written for the model, an input schema, and three annotations: readOnlyHint, destructiveHint and openWorldHint. The annotations are worth honoring in your agent. Read-only tools can run without asking. Destructive ones (delete_trip, edit_trip with removals, manage_crew) deserve a confirmation. Open-world ones (search_stays, search_activities, import_video) reach live partner inventory and take a few seconds.

Tools fall into groups: trip creation and editing, the one-call planner, place discovery and research, hotel and stay search, activity search, video and text import, saved places and tips, crew and chat, publishing, receipts and travel essentials, and the traveler profile. The grouped list with descriptions is on /mcp/tools.

Connect from a client you already have

Claude Code:

claude mcp add --transport http dreamfare https://api.dreamfare.app/mcp

Cursor, in .cursor/mcp.json:

{ "mcpServers": { "dreamfare": { "url": "https://api.dreamfare.app/mcp" } } }

VS Code, in .vscode/mcp.json:

{ "servers": { "dreamfare": { "type": "http", "url": "https://api.dreamfare.app/mcp" } } }

The first tool call returns a 401 with a WWW-Authenticate header that points at the resource metadata document. Clients that implement the MCP authorization spec follow it automatically: they discover the authorization server, register themselves, open a browser to dreamfare.app, and come back with a token. From then on the agent acts as that traveler.

Get through OAuth from your own code

If you are writing the client yourself, the flow is the standard one.

1. Fetch https://api.dreamfare.app/.well-known/oauth-protected-resource to find the authorization server, then its /.well-known/oauth-authorization-server document for the endpoints.
2. Register a client with token_endpoint_auth_method: "none". This matters: a client registered without it is confidential, and the token exchange will then demand a client secret you do not have. Real MCP clients register as public clients with PKCE.
3. Send the traveler to the authorization URL with a PKCE challenge. They sign in on dreamfare.app (or sign up on the way).
4. Exchange the code for a token and put it in the Authorization: Bearer header on every /mcp POST.

Tokens expire and refresh like any OAuth token. Store the refresh token, not the password, because there is no password to store.

A trip, from prompt to shared link

Here is the shape of a full run, with the tool for each step. Read the trip after every write: stops are enriched with pins, photos and booking links a few seconds after they land, and that is what the traveler will want to see.

1. create_trip with the destination, dates and a day-by-day list of stops. Pass the whole plan in one call. The response carries the trip id and each stop's id.
2. search_stays for the same dates and city with a nightly budget. Every amount includes taxes and fees; nightly is total divided by nights.
3. add_option_to_trip with the chosen stay object from the search result, kind stay. It lands on the check-in day.
4. search_activities, then add_option_to_trip with kind activity and a date.
5. get_trip to read it back with booking links, the packing list and, on shared trips, the vote tallies.
6. invite_to_trip to make an editor link, or email one person, so the traveler's crew can open it in the app.
7. share_trip with publish when the trip is done. This finalizes it, gives it a public dreamfare.app/p/… page, and lists it on Explore, where other travelers can copy it.

Two more flows are common. A video import is import_video, then get_import until the status settles, then add_saved_places_to_trip with the import id, which carries the extracted places over with their pins and tips intact. Starting from a published trip is explore_trips by destination, then copy_trip with the publication id, then edit_trip.

Conventions that trip people up

• Money is in major units at this boundary. A stay at 120 USD a night is 120, with the ISO currency beside it. The app stores minor units; the server converts.
• Days are 0-based and most writes also accept a date. Stop ids come from get_trip, never from the model's memory of an earlier call.
• Imports and the one-call planner spend credits. import_video, import_text and plan_trip use the traveler's plan or credits exactly as the app does, and the tool result says so when a plan is needed. Nothing else costs anything.
• Roles are enforced. A trip has an owner and a crew with roles; edit_trip on a trip the traveler can only view is an error, not a silent no-op. Publishing finalizes the trip, and edits on a finalized trip are errors too.
• Flights need an airport code first. search_flights takes IATA codes, so resolve a place name with search_airports before calling it, then attach the chosen fare with add_flight_to_trip. Read priceBasis before you quote a number: it says whether the figure is a per-person average or a whole-party total, and every quote is indicative until the traveler books on the partner's own site. Only name the sites and prices a call actually returned.
• Retries can duplicate. create_trip has no idempotency key. If your agent retries a timed-out create, read list_trips first.

Interactive cards, when the host supports them

In Claude and ChatGPT, every tool result also renders as an interactive card (the trip on a map with day tabs, a stays grid with Add buttons, an import that polls itself). That is the MCP Apps extension, and it needs a host that implements it. Other clients receive the same results as structured JSON and text, which is what an autonomous agent wants anyway.

Where to go next

• Dreamfare MCP: travel tools for AI agents, the landing page with connection snippets, FAQ and example flows.
• The tool reference, read live from the server.
• How to use an AI travel agent, the traveler's side of the same server.
• Plan a trip with Claude, the same connector from a traveler's point of view.
• llms.txt, a plain-text map of Dreamfare for language models.