User Stories Bot

User Stories Bot MCP server

Let your agents record the demo. User Stories Bot records narrated demo videos of your app; its MCP server opens that pipeline to your AI agents. An MCP-capable agent asks for a narrated demo of a branch, follows the recording and hands the finished video, captions and user stories to your reviewers, with no pull request needed.

This repository holds documentation only. The server is hosted by User Stories Bot; its source is not in this repository and there is nothing to install or run locally.

• Endpoint: https://app.userstoriesbot.com/api/mcp (Streamable HTTP, POST)
• Authentication: Authorization: Bearer
• Tools: demo_record, run_status, videos_list, stories_get
• Registry name: com.userstoriesbot/mcp
• Full guide: https://userstoriesbot.com/docs/mcp

Who can use it

Paid plans; one API key per agent. An org admin creates API keys in the dashboard; they work on the Pro and Team plans. Each key belongs to the org whose GitHub App installation covers the repository, so install the User Stories Bot GitHub App on the repository first: https://github.com/apps/userstoriesbot-com

Get a key

1. Sign in and open API keys in the dashboard: https://app.userstoriesbot.com/dashboard/api-keys
2. Create a key and copy it once; it is shown a single time.
3. Paste it into your client with the snippets shown next to the key, or use the forms below.

Put your own key where a snippet shows , or export it as USB_MCP_KEY where a snippet reads ${USB_MCP_KEY}. Never commit the key.

The four tools

Every result carries the output above as structured content plus a one-line text summary. A refused call returns a reason instead of a run.

The brief says what to show, in plain words. It passes the same checks as a rerun request: no links, no commands, no instructions to the bot.

Connect a client

The server URL is the same for every client.

One-click install

• Install in VS Code
• Install in VS Code Insiders
• Install in Cursor
• Install in Visual Studio

VS Code asks for the key in a password prompt; in Cursor, replace the placeholder with your key; in Visual Studio, add the Authorization header afterwards.

VS Code

.vscode/mcp.json (Visual Studio reads it too), where VS Code asks for the key in a password prompt:

{ "servers": { "userstoriesbot": { "type": "http", "url": "https://app.userstoriesbot.com/api/mcp", "headers": { "Authorization": "Bearer ${input:usb_mcp_key}" } } }, "inputs": [{ "type": "promptString", "id": "usb_mcp_key", "description": "User Stories Bot API key", "password": true }] }

Claude Code

claude mcp add --transport http userstoriesbot https://app.userstoriesbot.com/api/mcp --header "Authorization: Bearer <USB_MCP_KEY>"

Or a .mcp.json file at the project root:

{ "mcpServers": { "userstoriesbot": { "type": "http", "url": "https://app.userstoriesbot.com/api/mcp", "headers": { "Authorization": "Bearer ${USB_MCP_KEY}" } } } }

Cursor

.cursor/mcp.json:

{ "mcpServers": { "userstoriesbot": { "url": "https://app.userstoriesbot.com/api/mcp", "headers": { "Authorization": "Bearer ${env:USB_MCP_KEY}" } } } }

Copilot CLI

copilot mcp add --transport http userstoriesbot https://app.userstoriesbot.com/api/mcp --header "Authorization: Bearer <USB_MCP_KEY>"

Copilot CLI and VS Code also read the portable ~/.copilot/mcp-config.json:

{ "mcpServers": { "userstoriesbot": { "type": "http", "url": "https://app.userstoriesbot.com/api/mcp", "headers": { "Authorization": "Bearer ${USB_MCP_KEY}" }, "tools": ["*"] } } }

Copilot coding agent

In the repository settings (Code, planning, and automation, then Copilot, then MCP servers), store the key as a secret named COPILOT_MCP_USB_KEY and add:

{ "mcpServers": { "userstoriesbot": { "type": "http", "url": "https://app.userstoriesbot.com/api/mcp", "headers": { "Authorization": "Bearer $COPILOT_MCP_USB_KEY" }, "tools": ["demo_record", "run_status", "videos_list", "stories_get"] } } }

run_status, videos_list and stories_get are marked read only; demo_record is not, because it starts a run.

Codex

export USB_MCP_KEY="<USB_MCP_KEY>"

codex mcp add userstoriesbot --url https://app.userstoriesbot.com/api/mcp --bearer-token-env-var USB_MCP_KEY

Or the ~/.codex/config.toml table (shared by the Codex CLI, the desktop app, the IDE extension and the Codex agent in Xcode):

[mcp_servers.userstoriesbot]

url = "https://app.userstoriesbot.com/api/mcp" bearer_token_env_var = "USB_MCP_KEY"

Any other client

Any MCP client that supports Streamable HTTP with an Authorization header can connect. Most read this shape:

{ "mcpServers": { "userstoriesbot": { "url": "https://app.userstoriesbot.com/api/mcp", "headers": { "Authorization": "Bearer <USB_MCP_KEY>" } } } }

The guide at https://userstoriesbot.com/docs/mcp covers JetBrains Junie and AI Assistant, Devin, Antigravity, Zed, Kiro, claude.ai custom connectors and Xcode.

Test the connection

The MCP Inspector lists the tools your key can call:

npx --yes @modelcontextprotocol/inspector@2 --cli --transport http --server-url https://app.userstoriesbot.com/api/mcp --header "Authorization: Bearer <USB_MCP_KEY>" --method tools/list --format json

Usage

Push the branch to GitHub first, then ask your agent, for example:

Record a demo of this branch with User Stories Bot: show the new checkout flow. Wait for the run to finish, then give me the video link, the captions and the story titles.

A typical session: the agent calls demo_record with the repository, the branch and a short brief, polls run_status until it finishes, then fetches videos_list and stories_get.

1. demo_record with { "repo": "acme/app", "branch": "feature/checkout", "brief": "Show the new checkout flow." } answers run queued; poll run_status with the runId and the dashboardUrl.
2. run_status with { "runId": " " }, every 30 seconds, until the status is succeeded, failed, cancelled or refused. On succeeded, each entry of videos carries the video url and its captionsUrl. On failed, no_demo or unsupported_stack, a setupBrief tells your coding agent what to change in the repository.
3. stories_get with { "runId": " " } returns the user stories and the demo steps the run covered; videos_list with { "repo": "acme/app" } lists the repository's guides and earlier runs.

Use one idempotencyKey per request: a retry with the same key returns the earlier run (already requested) instead of starting a new one.

Limits

A run started over MCP uses the credits of your plan like a run from a pull request. Calls are rate limited per key and per org; the limits for your plan are shown on the API keys page of the dashboard. An HTTP 401 means the key is missing or revoked; an HTTP 429 means wait a minute and retry.

Links

• Documentation: https://userstoriesbot.com/docs/mcp
• Official MCP Registry entry: https://registry.modelcontextprotocol.io/v0.1/servers/com.userstoriesbot%2Fmcp/versions/latest
• Website: https://userstoriesbot.com
• Contact: info@userstoriesbot.com