Runstream MCP Server

MCP (Model Context Protocol) server that lets AI assistants (Claude Desktop, ChatGPT, Cursor, etc.) interact with Runstream projects and artifacts.

Quick Setup

1. Get your credentials

Go to app.runstream.ai/settings/api-keys and create an API key. You need two values:

| Variable | Where to get it | |----------|----------------| | RUNSTREAM_API_KEY | Settings > API Keys — create a new key | | RUNSTREAM_ORG_ID | Settings > Organization — your org ID |

2. Configure your AI client

Claude Desktop

1. Open Claude Desktop > Settings > Developer > Edit Config
2. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "runstream": {
      "command": "npx",
      "args": ["-y", "@runstream/mcp@latest"],
      "env": {
        "RUNSTREAM_API_KEY": "your-api-key",
        "RUNSTREAM_ORG_ID": "your-org-uuid"
      }
    }
  }
}

3. Restart Claude Desktop.

Once configured, you'll see guided prompts in the "/" menu:

• Start Runstream — List projects, pick one, see existing artifacts
• Create PRD — Draft a PRD and push it to a project
• Continue Working — Review artifacts and pick up where you left off

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "runstream": {
      "command": "npx",
      "args": ["-y", "@runstream/mcp@latest"],
      "env": {
        "RUNSTREAM_API_KEY": "your-api-key",
        "RUNSTREAM_ORG_ID": "your-org-uuid"
      }
    }
  }
}

ChatGPT

ChatGPT doesn't support MCP prompts, but the tools work the same way. Connect the MCP server and use natural language:

• "List my Runstream projects"
• "Show me the artifacts in project X"
• "Create a PRD for [feature] and push it to project X"

Optional env vars

| Variable | Purpose | |----------|---------| | RUNSTREAM_API_URL | Override the API URL (defaults to https://api.runstream.ai) |

Available Tools

| Tool | Description | |------|-------------| | list_projects | List all projects in your organization | | list_artifacts | List artifacts in a project (optionally filter by status) | | get_artifact | Get a single artifact with full content | | push_artifact | Create a new artifact (PRD, spec, stories, etc.) | | update_artifact | Update an existing artifact | | get_project_context | Get project details + all published/approved artifacts |

Developer Setup (Full Server)

For developers who need the full MCP server with GitHub, review, deploy, and plan tools (from the monorepo):

{
  "mcpServers": {
    "runstream": {
      "command": "node",
      "args": ["/path/to/runstream/services/mcp/dist/index.js"],
      "env": {
        "RUNSTREAM_API_KEY": "your-api-key",
        "RUNSTREAM_ORG_ID": "your-org-uuid",
        "GITHUB_TOKEN": "your-github-pat",
        "ANTHROPIC_API_KEY": "your-anthropic-key"
      }
    }
  }
}

This requires cloning the monorepo and building:

pnpm install && pnpm --filter @runstream/mcp build

Development

# Build TypeScript (full server)
pnpm --filter @runstream/mcp build

# Bundle standalone for npm
pnpm --filter @runstream/mcp bundle

# Dev mode (auto-reload)
pnpm --filter @runstream/mcp dev

Troubleshooting

"RUNSTREAM_API_KEY is required"

• Make sure RUNSTREAM_API_KEY is set in your config's env block.
• Get a key from app.runstream.ai/settings/api-keys.

Tools not appearing?

• Restart Claude Desktop after config changes.
• Check Claude Desktop logs for error messages.

API errors (401, 403)?

• Check that your API key is valid and not expired.
• Check that your RUNSTREAM_ORG_ID matches the org the key belongs to.