Mainline MCP Server

AI Coding

How it works

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.

What the LLM can do

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

What only you do

• 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.

Setup (Claude Code)

1. Go to your team settings and generate an MCP token.
2. 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"
3. Optionally, give the LLM your deployment webhook token so it can report deploys. The MCP server includes the webhook URL in story responses.

Setup (other MCP clients)

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" } } } }

Available tools

list_maps

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

get_map

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.

get_story

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 workflow

1. The LLM calls list_maps then get_map to see the work.
2. You tell it which story to work on (or it picks the next active one).
3. It calls get_story to read the acceptance criteria.
4. It writes the tests and code, guided by the scenarios.
5. The code deploys. If it has the webhook token, it reports the deploy.
6. You verify the work and release the story when ready.

Deploy and release are separate events - use feature flags, dark launching, or branch by abstraction to decouple them.

Privacy

The MCP token gives read-only access. No personal information is exposed. Story assignments show a count, not names. The LLM cannot modify your map, create stories, or mark anything as released in Mainline.

Security

The MCP token and deploy webhook token are separate. You can give the LLM read access without deploy access, or both. Tokens are shown only once when generated.