Journeys MCP Server
Turn exposes the tools Ripple, the AI co-pilot in the journey builder, uses to build journeys as a Model Context Protocol server, so you can build, fix and try journeys from your own AI agent, such as Claude Code, and test them with your own tooling through the Journeys Simulation API.
This server is under active development and its tools may change.
Connecting
The server lives at https://whatsapp.turn.io/v1/mcp and uses the same authentication as every other API call: a Turn.io token for the number, sent in the Authorization header. Every tool works on that number's journeys.
To connect Claude Code:
$ claude mcp add --transport http turn https://whatsapp.turn.io/v1/mcp \
--header "Authorization: Bearer token"
Any MCP client that supports the Streamable HTTP transport and custom headers can connect the same way.
Tools
| Tool | What it does |
|---|---|
GetAuthoringGuide | How to write journeys, in parts: overview (rules for card copy, AI agents or fixed flows, the code tools, DSL basics), cards (every card type), expressions (variables, logic, functions), example (a complete journey), number (the number's contact fields, AI models and languages), skills and templates (the number's skills and WhatsApp templates). A part too long for one result comes in pages. |
ListJourneys, GetJourney, CreateJourney | Find, read and create journeys. Every result includes the journey's canvas URL. |
ReplaceAllCode, EditJourney | Write a whole journey, or change some of its cards. The code is validated first: when it does not validate, nothing is saved and the result says what to fix. |
GetTranslations, UpdateTranslations | Read and write the journey's translations. |
RenameJourney | Rename a journey. |
GetSkills, CreateSkill, UpdateSkill, DeleteSkill | Manage the number's AI agent skills. |
CreateContactField | Add a contact field to the number. |
ListSecrets, GetTemplate, GetJourneyExample | Look up the number's secrets (names only), WhatsApp templates and curated journey examples. |
Simulate | Play a turn of a simulated conversation with a journey. It takes and returns the same fields as the Journeys Simulation API. |
When the number has journey tests, WriteTests, EditTests and RunTests are offered too.
Building and testing a journey
When an agent connects, the server tells it how to work:
- Read the authoring guide (
overview,cardsandnumberat least). - Create the journey and write it with
ReplaceAllCode, then change it withEditJourney, fixing whatever validation reports. - Open the canvas URL to show what was built. Reload the page after an edit to see the change.
- Try it with
Simulate. - Write a test suite against the Journeys Simulation API with the same token, run it, and edit the journey over MCP until it passes.
Notes
- Every edit is saved as a new, unpublished revision of the journey, tagged as made through MCP.
Simulateplays the latest saved revision unless asked forproduction. Publish from the canvas when you are happy with it. - Changes to contact fields and to skills shared by other journeys affect every journey on the number, so an agent should ask you before making them.