Using with Cursor - Boundary Documentation

Boundary integrates seamlessly with Cursor IDE through the Model Context Protocol (MCP). This guide covers setup, configuration, and best practices.

Overview

Boundary relies entirely on your IDE's code intelligence to provide comprehensive context. Cursor acts as Boundary's eyes and ears, using LSP, "Go to Definition", and "Find References" to gather the code context needed for thorough debates.

The collaboration is iterative: Boundary generates semantic queries about your codebase, and Cursor investigates using its superior code intelligence to provide context. This process repeats over multiple rounds until Boundary has everything needed to complete the debate.

MCP Setup

Step 1: Configure Cursor MCP Settings

Open Cursor's MCP settings (typically in Settings → MCP or via the MCP configuration file). Add Boundary as an MCP server:

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

Step 2: Restart Cursor

After configuring the MCP server, restart Cursor to establish the connection. You should see Boundary available in Cursor's MCP tools.

Step 3: Verify Connection

Test the connection by asking Cursor to list available MCP tools. You should see Boundary's debate tools available:

debate_start - Initiate a new debate session
debate_continue - Continue an ongoing debate with context
list_agents - List all available debate agents with their descriptions, biases, and evaluation axes
record_decision - Record a decision after debate completion

Initiating Debates

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 in Cursor 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. Cursor will then work with Boundary iteratively, providing context as needed until the debate completes.

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

The Iterative Process

Boundary's debate process is iterative and collaborative:

Boundary generates queries: After analyzing your question, Boundary generates specific semantic queries about symbols, boundaries, call graphs, and implementations it needs to understand.
Cursor investigates: Cursor uses its code intelligence: LSP, "Go to Definition", "Find References", codebase search to gather comprehensive context. It extracts code snippets, traces dependencies, and finds related patterns.
Context is provided: Cursor sends the gathered context back to Boundary via debate_continue.
Process repeats: This cycle continues over multiple rounds. Boundary may ask for deeper analysis of specific components, edge cases, or dependencies. Cursor continues investigating until Boundary has everything needed.
Debate completes: Once Boundary has sufficient context, it completes the multi-agent debate and returns a decision map. Cursor displays this to you, showing the risk surfaces, trade-offs, and failure modes.

Providing Context

You can help the process by:

Specifying context files: When initiating a debate, you can provide specific files or directories that are relevant to your decision.
Answering queries directly: If Boundary asks for specific information, you can provide it directly to Cursor, which will pass it along.
Being specific: The more specific your question, the better Boundary can generate targeted queries and provide relevant analysis.

Reading Results

When a debate completes, Boundary returns a decision map that includes:

Risk surfaces: Concrete failure vectors that emerge from the agent conflict
Trade-offs: Competing engineering values and their implications
Irreversible commitments: Decisions that will be difficult or impossible to undo later
Assumption dependencies: Hidden assumptions that the decision relies on
Agent perspectives: The positions taken by each agent and their reasoning

For detailed guidance on interpreting decision maps, see Decision Maps.

Recording Decisions

After a debate completes, you can record the final decision using the record_decision tool. This creates a structured decision record that captures the decision, rationale, participants, and context for future reference.

How to Record a Decision

Once a debate is complete, ask Cursor to record the decision. You need to provide:

Session ID: The identifier from the completed debate session
Decision: The decision that was taken (e.g., "Use Redis for caching")
Rationale: Why this decision was chosen, including key considerations from the debate
Decision Makers (optional): Names and contact information of people who made the decision
Disagreement Choices (optional): Alternative options that were considered but not chosen

What Happens When You Record a Decision

When you record a decision, Boundary creates a comprehensive decision record that includes:

Decision details: The decision, rationale, and timestamp
Debate context: The original question, session information, and context files used
Participants: All agents that participated in the debate and the number of context rounds
Decision makers: People involved in making the decision (if provided)
Related reports: Links to the debate README.md and decision matrix if they exist

The decision record is saved in two formats:

JSON file: Machine-readable format for programmatic access and integration
Markdown file: Human-readable format for documentation and review

Both files are saved in the same folder as the debate results, making it easy to find all related documentation together. The record includes links to related reports (executive summary and decision matrix) if they were generated during the debate.

Note: You can only record decisions for completed debates. The debate session must have a status of "complete" before recording is allowed.

Best Practices

Frame decisions clearly: Be specific about what you're deciding and why it matters. Vague questions lead to less useful debates.
Provide relevant context: Include files, directories, or code snippets that are directly relevant to your decision.
Be patient with iterations: The iterative process ensures comprehensive analysis. Let Cursor and Boundary work through multiple rounds.
Review the full decision map: Don't just look for a verdict. The value is in understanding the risk surfaces and trade-offs.
Record important decisions: Use the record_decision tool to save decisions for future reference.

Using Boundary with Cursor