> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP integration

> Connect AI-powered editors to GoRules BRMS through the Model Context Protocol.

The [GoRules CLI](/developers/cli) exposes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI assistants interact with your GoRules BRMS projects. When connected, AI tools can read, modify, simulate, and test your decision graphs directly.

## How it works

The GoRules CLI starts a lightweight MCP server that connects to your browser session via WebSocket. When an AI assistant sends a tool call, the CLI forwards it to the GoRules web app running in your browser, which executes the operation against your in-memory decision graphs and returns the result.

```mermaid theme={null}
graph LR
    A[AI Assistant] <-->|MCP| B[GoRules CLI]
    B <-->|WebSocket| C[GoRules Browser Editor]
```

This architecture keeps all execution local - decision graphs are evaluated in your browser, and no data leaves your machine.

## Setup

### 1. Start the MCP server

```bash theme={null}
npx @gorules/cli mcp start
```

The CLI starts on port `41919` by default and generates an 8-character token displayed in the terminal.

### 2. Connect in the browser

1. Open GoRules in your browser and navigate to a branch.
2. Click the **MCP Server** button in the editor toolbar.
3. Enter the 8-character token from the terminal.
4. The status dot turns green when connected.

### 3. Configure your AI assistant

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add gorules --transport http http://localhost:41919/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "gorules": {
          "url": "http://localhost:41919/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP config:

    ```json theme={null}
    {
      "mcpServers": {
        "gorules": {
          "url": "http://localhost:41919/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other providers">
    Any MCP client that supports Streamable HTTP can connect:

    ```json theme={null}
    {
      "mcpServers": {
        "gorules": {
          "url": "http://localhost:41919/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Available tools

Tools are dynamically registered by the GoRules browser editor when it connects. The exact tools depend on your project, but generally cover graph introspection, graph mutation, decision table operations, simulation, test management, and file operations.

<Tip>
  The MCP server instructs AI assistants to call `get_current_context` first. This provides the assistant with full context about available tools and the connected project.
</Tip>

## Connection status

The **MCP Server** button in the GoRules toolbar shows the connection state:

| Status       | Indicator         | Meaning                                         |
| ------------ | ----------------- | ----------------------------------------------- |
| Connected    | Green pulsing dot | MCP server is active and linked to your session |
| Connecting   | Amber dot         | WebSocket connection is being established       |
| Disconnected | Gray dot          | No active connection                            |

Click the **MCP Server** button again to disconnect.

## Configuration

| Option         | Default     | Description                                 |
| -------------- | ----------- | ------------------------------------------- |
| `--port`, `-p` | `41919`     | Port the bridge listens on                  |
| `--host`, `-h` | `localhost` | Host the bridge binds to                    |
| `--url`, `-u`  | -           | GoRules server URL (used with `--open`)     |
| `--open`       | `false`     | Open the GoRules editor in browser on start |

## Security

* Connections are authenticated with an 8-character token generated per session.
* All tool execution happens in your browser - decision graphs are never sent to the CLI or AI assistant directly.
* The WebSocket connection runs on `localhost` only.
* Only one browser tab can be active on the MCP bridge at a time.

## Troubleshooting

**"Browser not connected"** - The GoRules editor hasn't connected yet. Open your project and click **MCP Server**.

**"Tool execution timed out (60s)"** - The browser tab may be in the background or unresponsive. Bring the GoRules editor tab to the foreground.

**"Browser disconnected"** - The WebSocket connection was lost. Reconnect from the GoRules editor.