Mainline

Your AI coding assistant connects to Mainline and reads your user story map. It sees the activities, tasks, stories, and acceptance criteria. Then it works on one story at a time.

When the code deploys, the LLM can report the deployment automatically if you set up the deploy webhook (in your team settings) and give the LLM the deploy token. You decide when to release.

- Read the map structure: activities, tasks, stories, release slices, personas
- Read a story's detail: description, scenarios (given/when/then, each with its verified/done state), deploy history
- Report a deployment via the webhook API (if you give it the deployment token)

- Design the user journey
- Write the stories and acceptance criteria
- Release stories to users
- Decide what to work on next

Whether you are coding with LLM assistance or not, we recommend test-driving development. Start with a BDD-style scenario that describes the behaviour, then choose the right type of test for what is being verified, e.g. unit, acceptance, or contract.

- The 4-layer test strategy (test cases, DSL, drivers, SUT) described in Humble, J. and Farley, D. (2010)Continuous Delivery. Boston: Addison-Wesley. The DSL layer works particularly well with LLMs. It keeps test context in domain language rather than low-level implementation, so the LLM writes meaningful tests without coupling to internals.
- Behaviour-Driven Development, described in Smart, J.F. (2014)BDD in Action. Shelter Island: Manning. Scenarios written as given/when/then map directly to what Mainline stores on each story. The LLM reads the scenarios and knows exactly what to test.

This works when you have acceptance criteria on your stories and a test suite the LLM can run. Without both, the LLM is guessing and you have no way to verify its work. If you don't have these yet, start with the practices above before connecting an AI assistant.
- Go to your team settings and generate an MCP token.
- Run this in your project directory:

claude mcp add --transport http mainline \ https://mainline.dev/mcp/YOUR_TEAM_ID \ --header "Authorization: Bearer YOUR_MCP_TOKEN"

For editors and tools that use a JSON config file, add this to your MCP configuration:

{ "mcpServers": { "mainline": { "url": "https://mainline.dev/mcp/YOUR_TEAM_ID", "transport": "streamable-http", "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } } } }

Lists all maps for your team. Start here to get the map ID.

Returns the full map hierarchy: activities, tasks, and stories with their status and position. Also includes personas and release slices. This gives the LLM the big picture of your product.

Returns a single story's full detail: description, scenarios (given/when/then acceptance criteria), deploy count, and the deployment webhook URL. This is what the LLM reads before starting work on a story.
- The LLM callslist_mapsthenget_mapto see the work.
- You tell it which story to work on (or it picks the next active one).
- It callsget_storyto read the acceptance criteria.
- It writes the tests and code, guided by the scenarios.
- The code deploys. If it has the webhook token, it reports the deploy.
- You verify the work and release the story when ready.

Deploy and release are separate events - usefeature flags, dark launching, or branch by abstractionto decouple them.

Local stdio MCP server that lets AI coding agents read and maintain structured architecture, rules, and decisions directly from your repository.