Goyondo + Claude Code and Claude Desktop
Last verified
Add Goyondo to Claude Code with claude mcp add goyondo -- npx -y goyondo-mcp. Your assistant can then use create_trip, add_activity, run_alignment, get_edit_log and list_trips to plan and edit trips that persist in Goyondo.
Connect Claude Code and Claude Desktop to Goyondo
- Add the server. In Claude Code run claude mcp add goyondo -- npx -y goyondo-mcp. In Claude Desktop open Settings → Developer → Edit Config and add "goyondo": { "command": "npx", "args": ["-y", "goyondo-mcp"] } under mcpServers, then restart.
- First call starts sign-in. goyondo-mcp starts the OAuth device flow (POST /api/agent-auth/device) and returns a goyondo.run/connect link, which Claude shows to the user.
- The user approves one link. The user signs in, reviews the requested scopes and taps Grant access. goyondo-mcp polls for the gyd_ key and saves it to ~/.config/goyondo/credentials.json, readable only by that user. Keys last 90 days by default.
- Call tools. Each MCP tool call is sent to POST https://goyondo.run/api/mcp/tools/call with the saved key. Agents that do not speak MCP can call that endpoint directly; see /developers.
Example prompts
Connect to Goyondo and list my trips.Create a Goyondo group trip for four friends going to Seoul in October and give me the join link.For group trip ABC123, run Group Harmony alignment and summarise where we still disagree.Tools your assistant can use
| Tool | What it does |
|---|---|
describe_capabilities | Describe available Goyondo agent capabilities, including input schemas, enum values, and supported interfaces. Use this for introspection before calling other capabilities. |
get_schema | Return the JSON input schema for one Goyondo capability, or all schemas if no capability is provided. |
list_trips | List trips for the authenticated user. Returns trip id, destination, dates, status. Supports limit; response includes has_more to indicate whether more trips exist. |
get_trip | Get a single trip by id including full itinerary (days and activities). |
create_trip | Create a new trip and optionally generate an AI itinerary. Returns the created trip and itinerary. |
update_trip | Update trip metadata such as dates, title, traveler count, budget, or status. When start_date or end_date changes, the response includes itinerary_dates showing the first and last day dates after the shift — verify these match your intended dates before proceeding. |
regenerate_itinerary | Regenerate the AI itinerary for an existing trip. |
add_activity | Add an activity to a trip. To assign to a specific day use itinerary_id (UUID from get_trip itinerary days — most reliable), date (YYYY-MM-DD), or day_number (1-based). If none are provided the activity lands on Day 1. |
update_activity | Update an existing activity. All fields except trip_id and activity_id are optional. |
list_activities | List all activities for a trip as a flat array. |
delete_activity | Delete an activity from a trip. |
list_bookings | List bookings for the authenticated user. |
get_booking | Get a single booking by id. |
create_booking | Record a booking the user made elsewhere (flight, hotel, activity) so it stays with the trip. Goyondo does not place bookings or take payment. |
check_availability | Check the user's existing Goyondo booking records for a destination and dates. This is not live supplier availability or pricing. |
get_user_preferences | Get the authenticated user's travel preferences (interests, dietary, accessibility, etc.). |
list_itinerary_segments | List business traveler segments for a trip (flights, hotels, car rentals, meetings). |
get_trip_document | Get a trip document by id or search by name (e.g. boarding pass for flight SQ321). |
get_trip_expense_summary | Get expense summary for a trip (for expense report export). |
submit_group_preferences | Submit group trip preferences for alignment (Group Harmony). Use trip_code from the share link. |
submit_group_inspiration | Submit a link, raw text, or explicit place to a group inspiration board. Use trip_code from the group share link. Provide exactly one of url, text, or place. |
get_group_board | Get the collaborative inspiration board for a group trip, including candidates, reactions, review lane, and readiness signals. |
react_to_place | Vote on a place candidate in a group inspiration board. Agent votes are advisory until the human member confirms them. |
update_place_candidate | Confirm, edit, or ignore a review-lane place candidate on a group inspiration board. When a human member calls this with action="confirm" the place becomes binding for the trip (agent react_to_place votes are advisory only). |
update_user_preferences | Update the authenticated user's travel preferences. |
create_group_trip | Create a new group trip. Returns trip_code and join_url that members use to join. The caller becomes the creator (and default lead agent). Agent actions on this trip are attributed to the creating member. |
list_group_trips | List all group trips the authenticated user belongs to. Returns an array of { trip_code, status, role, title, id, ... }. role is one of "creator" or "member". Requires the group_trips:read scope. |
delete_group_trip | Delete a group trip and its members, preferences, and alignment data. Creator only — other members receive a 403. Requires the group_trips:write scope. |
join_group_trip | Join an existing group trip using its trip_code. |
get_group_trip | Get a group trip by its trip_code, including members and current preferences. |
run_alignment | Trigger Group Harmony alignment — AI reconciles all member preferences (only dates, destination, and budget are reconciled) and produces a consensus plan. Lead agent only. Each call runs the next round; the default max is 2 rounds before the trip moves to escalation_pending (the creator can then call extend-rounds). Every round sets a response_deadline 48h out; members who have not resubmitted a response by the time the next round runs are auto-accepted and returned in timed_out_members. |
get_alignment | Get the latest Group Harmony alignment result for a group trip: consensus_items, conflicts, proposed_destination, proposed_dates, round_number, response_deadline (48h per round), and alignment_score (20/45/70/95 for 0/1/2/3 of dates+destination+budget reconciled). Use GET /api/group-trips/:trip_code/alignment/rounds for full per-round history and GET .../alignment/status for the poll view including timed_out / pending members. |
list_proposals | List pending change proposals for a trip (editors and owners only). |
approve_proposal | Approve a pending change proposal on a trip. |
reject_proposal | Reject a pending change proposal on a trip. |
get_edit_log | Get the edit history for a trip, including agent and human changes. |
set_user_preference | Record a travel preference on behalf of the authenticated user. Use this when the user states a preference during conversation (e.g. "I prefer window seats", "I am vegetarian", "I like boutique hotels"). The preference is stored as a signal and their AI travel profile is updated automatically. |
get_preference_profile | Get the authenticated user's AI-rendered travel preference profile (full markdown doc). Useful before creating a trip or making personalised recommendations. |
update_day_notes | Set or replace the notes for a specific itinerary day. Day notes are free-text and visible in the travel view. Use this to record how a day went, note plan deviations, or add context for a day. Provide either day_id (UUID from get_trip itinerary.days[n].id) or day_number (1-based integer); day_id is preferred when available. |
Frequently asked questions
- Does this work with claude.ai or the Claude mobile app?
- Not yet. goyondo-mcp is a local stdio MCP server, so it runs where Claude Code or Claude Desktop runs. claude.ai and the mobile apps need a remote MCP connector, which Goyondo does not offer yet.
- Which scopes can Claude request?
- trips:read, trips:write, bookings:read, bookings:write, preferences:read, group_trips:read and group_trips:write. The user sees the requested scopes before approving.
- Is there an optional Claude Code skill?
- Yes. Install it with mkdir -p ~/.claude/skills/goyondo && curl -fsSL https://goyondo.run/api/agent/skill -o ~/.claude/skills/goyondo/SKILL.md. It is behavior guidance only, such as placing activities by itinerary_id and re-reading the trip after every write; it does not change what the tools can do.
- Can the user revoke Claude's access?
- Yes. Keys are listed under API keys in the user's Goyondo profile and can be revoked at any time. Every change Claude makes appears in the trip's edit log.