> ## 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 Claude, ChatGPT, and other AI assistants to GoRules through the Model Context Protocol.

GoRules supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) in two ways:

* **Remote MCP**: a hosted MCP server built into GoRules. Connect Claude, ChatGPT, or any MCP client with a URL, no installation required.
* **Local MCP**: a developer bridge through the [GoRules CLI](/developers/cli) that connects local AI editors to the workspace open in your browser.

## Remote MCP

Remote MCP gives AI assistants direct access to your GoRules organisation. An assistant can browse projects, read and edit graphs and policies, run tests and evaluations, and commit changes or open merge requests, always with your own permissions.

### Server URL

Point your MCP client at your GoRules host followed by `/api/mcp`:

```
https://<tenant>.us1.gorules.io/api/mcp
```

Use `eu1` instead of `us1` for the Europe region, or `https://<your-host>/api/mcp` for a self-hosted installation.

There is nothing to configure in GoRules beforehand. The client registers itself automatically (OAuth dynamic client registration) and opens a GoRules sign-in page where you approve access.

### Connect Claude

1. In Claude, open **Settings > Connectors**.
2. Click **Add custom connector**.
3. Enter a **Name** (for example `GoRules`) and the **MCP server URL** from above.
4. Click **Continue**, then sign in to GoRules and click **Allow**.

On Team and Enterprise plans, an owner adds the connector once under **Organization settings > Connectors**, and each member clicks **Connect** to sign in with their own account.

### Connect ChatGPT

1. Turn on developer mode in **Settings > Security and login > Developer mode**.
2. Go to [ChatGPT Plugins](https://chatgpt.com/plugins) and click the **+** button.
3. Enter a name and description, and under **Connection** enter the MCP server URL from above.
4. Select **OAuth** as the authentication method and create the connection.
5. Sign in to GoRules and click **Allow**.

On Business, Enterprise, and Edu workspaces, developer mode is managed by workspace admins, who create the app and publish it for members.

### Approval and access

The first time an app connects, it must be allowed for your organisation:

* When an **administrator** connects it, the app is enabled for the whole organisation.
* When a **member** connects it first, the request waits for an administrator. Once approved in **Settings > Integrations & Apps**, the member connects again.

Each user can see and revoke their own connections under **Settings > Profile > Connected apps**. Administrators can disable or remove an app for everyone from **Integrations & Apps**.

### How changes are saved

Edits made by an assistant go to a private working copy for the branch, just like editing in the browser. Nothing is committed until the assistant commits the working copy. Committing from `main` creates a new branch and opens a merge request for review.

### Self-hosted prerequisites

* **Secrets encryption**: remote MCP signs its OAuth tokens with per-organisation keys that are stored encrypted with your KEK/DEK setup. Configure a production key provider first, see [Secrets management](/developers/deployment/brms/secrets-management).
* **Public HTTPS URL**: Claude and ChatGPT connect from the internet, so GoRules must be reachable over HTTPS at its configured app URL.
* **Enabled flag**: remote MCP is controlled by the `MCP_ENABLED` environment variable.

## Local MCP

The local bridge is intended for developers using AI editors such as Claude Code or Cursor. The [GoRules CLI](/developers/cli) runs an MCP server on your machine and forwards tool calls to the GoRules workspace open in your browser, so assistants work on exactly what you have open, including unsaved changes.

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

### Setup

1. Start the bridge:

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

   The CLI listens on `localhost:41919` and prints an 8-character token.

2. In GoRules, open **Developer Tools**, select **MCP Server (local)**, and paste the token. The status changes to **Connected**.

3. Add the server to 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="Other clients">
    Any MCP client that supports Streamable HTTP can connect:

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

### CLI options

| 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 GoRules in the browser on start |

### Troubleshooting

* **"Browser not connected"**: open **Developer Tools > MCP Server (local)** and paste the token from the CLI.
* **Connection blocked**: the browser is blocking local network access. Allow it in the site permissions next to the address bar, then reload.
* **"Tool execution timed out"**: the GoRules tab may be in the background. Bring it to the foreground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.