Getting Started - Boundary Documentation

Get up and running with Boundary in minutes. This guide will walk you through installation, setup, and your first debate.

What is Boundary?

Boundary is a cloud-first, open-source, MCP-native multi-agent debate system that helps you stress-test engineering decisions before they harden. You can fork and run it locally when you need full control. Instead of providing a single answer, Boundary surfaces hidden assumptions, irreversible commitments, and failure modes through structured debates between opinionated AI agents.

The output is not a verdict, it's a decision map that illuminates the risk surfaces and trade-offs inherent in your engineering choices.

Prerequisites

Before you begin, ensure you have the following:

Docker: Boundary runs as a containerized MCP server. Install Docker Desktop or Docker Engine on your system.
Cursor IDE: Boundary integrates with Cursor via the Model Context Protocol (MCP). Cursor provides the code intelligence that Boundary needs to understand your codebase.
LLM API Keys: At least one of the following:
- OPENAI_API_KEY (recommended for default usage)
- ANTHROPIC_API_KEY
- GOOGLE_API_KEY

Quickstart

Get Boundary running in 4 simple steps:

Step 1: Pull the Docker Image

Pull the official Boundary MCP server image from GitHub Container Registry:

docker pull ghcr.io/boundary-mcp/boundary-mcp:latest

Step 2: Configure Cursor MCP Settings

Edit ~/.cursor/mcp.json and add one of the following configurations:

Option 1: Using an Environment File

Use this option if you prefer to store your API keys in a .env file:

{
  "mcpServers": {
    "boundary": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/your/.env",
        "ghcr.io/boundary-mcp/boundary-mcp:latest"
      ]
    }
  }
}

Replace /path/to/your/.env with the absolute path to your .env file (created in Step 3).

Option 2: Using Environment Variables Directly

Use this option to pass environment variables directly with the -e flag:

{
  "mcpServers": {
    "boundary": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAI_API_KEY=your-key-here",
        "-e",
        "ANTHROPIC_API_KEY=your-key-here",
        "-e",
        "GOOGLE_API_KEY=your-key-here",
        "-e",
        "MCP_TRANSPORT=stdio",
        "ghcr.io/boundary-mcp/boundary-mcp:latest"
      ]
    }
  }
}

Replace the placeholder values with your actual API keys. At least one API key is required. You can omit optional keys you don't need.

Step 3: Set Environment Variables

Create a .env file with your API keys:

OPENAI_API_KEY=your-key-here
# Optional:
ANTHROPIC_API_KEY=your-key-here
GOOGLE_API_KEY=your-key-here
MCP_TRANSPORT=stdio

At least one API key is required. OpenAI is used by default if available.

Step 4: Install Cursor Commands

Create the Cursor commands directory:

mkdir -p ~/.cursor/commands

Create Command Files

Create the following files in ~/.cursor/commands/:

prepare-boundary-debate.md

You are helping me prepare the input for a Boundary debate by analyzing the decision question, exploring the codebase, identifying relevant context, and refining the question with constraints, invariants, and non-goals.

## Purpose

This command prepares high-quality inputs for the `start-boundary-debate` command by:
1. Understanding the decision question and its scope
2. Exploring the codebase to find all relevant files and context
3. Identifying constraints, invariants, and patterns from the codebase
4. Refining the question with additional context and clarifications
5. Suggesting relevant context files and agent configurations

## Input

- `<DECISION_QUESTION>` - The initial engineering decision question to analyze and refine
- `<INITIAL_CONTEXT>` (optional) - Comma-separated list of file paths to start the analysis from

## Process

### 1. Understand the Question

Analyze the decision question to understand what is being decided, why it matters, scope, key concerns (performance, scale, error handling, etc.), and domain. Extract key terms, concepts, and entities.

### 2. Initial Context Discovery

If `<INITIAL_CONTEXT>` is provided, read each file to understand its purpose, identify key functions/classes/models, extract domain concepts and patterns, and note constraints/validations/invariants.

start-boundary-debate.md

You are helping me start an engineering decision debate using the Boundary MCP server. This requires an **iterative workflow** where you'll provide context multiple times until the debate is complete.

## Context

Boundary relies **entirely on you** to provide code context. You have access to Cursor's superior code intelligence (LSP, "Go to Definition", "Find References", etc.) that Boundary cannot access directly. Your role is to gather and provide comprehensive context through multiple iterations.

**Before starting the debate, you MUST proactively investigate and identify all relevant context.**

Use your code intelligence tools to search for related files, functions, and classes; trace dependencies; find similar implementations; identify related services, models, and utilities; and discover edge cases and error handling patterns.

Be generous with context: Include all files that touch the decision area (even tangentially), related models/schemas, service dependencies, error handling, existing patterns, configuration, and related tests.

## Input

I will provide either:

**Option 1: Prepared Debate File (Most Common)**
- `<PREPARED_DEBATE_FILE>` - Path to a markdown file from `prepare-boundary-debate` output (e.g., `.cursor/boundary-debates/my-decision.md`)

**Option 2: Direct Inputs**
- `<DECISION_QUESTION>` - The engineering decision question to debate
- `<CONTEXT_FILES>` (optional) - Comma-separated list of file paths
- `<AGENT_CONFIG>` (optional) - Agent configuration in list format (`"pragmatist: OpenAI gpt-4"`), JSON format, or comma-separated. Multiple agents of the same type are allowed.
- `<ROUNDS>` (optional) - Number of debate rounds (default: 1)

Restart Required

Restart Cursor to load the commands.

Ideal Workflow

Boundary works best when you follow a three-step process. This approach ensures you have high-quality inputs and get the most valuable debate output.

Prepare the Debate

Use the prepare-boundary-debate command to analyze your question and gather context.

This command will:

Analyze your decision question and its scope
Explore the codebase for relevant files and context
Identify constraints, invariants, and patterns
Refine the question with additional context
Generate a list of recommended context files
Suggest relevant agent configurations

Example:

/prepare-boundary-debate "Should we use Redis or PostgreSQL for caching?"

Refine the Generated Document

Review the output from Step 1 and make any necessary adjustments before starting the debate.

Check that:

All relevant files are included in the context list
Constraints and invariants are accurate
The refined question captures your intent
Agent configuration matches your needs
Any missing context is added

This refinement step ensures the debate has the best possible inputs, leading to more valuable insights.

Start the Debate

Use the start-boundary-debate command with the prepared debate file from Step 1.

Simply provide the path to the prepared debate file. The command will automatically extract:

The refined question with constraints and invariants
The recommended context files list
The suggested agent configuration

Example:

/start-boundary-debate .cursor/boundary-debates/my-decision.md

The command will parse the prepared file and start the debate with all the refined inputs. The debate will run iteratively, with Boundary asking for additional context as needed until completion.

Note: Direct inputs are still supported for backward compatibility, but using a prepared debate file is recommended for the best results.

Why This Workflow?

The prepare → refine → start workflow ensures:

Better context: Comprehensive codebase exploration before the debate starts
Clearer questions: Refined questions with constraints and invariants lead to better debates
More valuable output: Well-prepared inputs result in more actionable insights
Time savings: Fewer iterations during the debate itself

Next Steps

Now that you've run your first debate, explore these resources:

Using with Cursor - Detailed MCP setup and integration guide
Agent Types - Understand the different agent perspectives
Decision Maps - Learn how to read and interpret decision maps
FAQ - Common questions and troubleshooting