# BRP MCP Server

[![PyPI version](https://img.shields.io/pypi/v/brp-mcp.svg)](https://pypi.org/project/brp-mcp/)

A standalone FastMCP server that exposes Lantern BRP gateway APIs dynamically from a single OpenAPI spec. 

This package is designed to be easily used by AI agents (like **Cursor** and **Claude Desktop**) via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It supports local `stdio` transport and remote `sse` transport, automatically converting API definitions into actionable AI tools.

## Features
- **Dynamic Tools:** Fetches the BRP OpenAPI spec on startup and converts endpoints into AI-friendly tools.
- **Secure Authentication:** Built-in Auth0 M2M flow and bearer token pass-through to secure API calls to the gateway.
- **Environment Profiles:** Pre-configured environments (`dev`, `stage`, `prod`).
- **Visibility Policies:** Granular endpoint exposure mapping using OpenAPI extensions or a local JSON policy.
- **Zero-config run:** Run instantly via `uvx` without needing a local python environment setup.

---

## Installation

You can install the package directly from PyPI using your favorite package manager:

```bash
pip install brp-mcp
```

Or run it ephemerally with [uv](https://docs.astral.sh/uv/):
```bash
uvx brp-mcp
```

---

## Usage in Cursor / AI Agents

If you want to provide Cursor or Claude with access to the BRP API, you can add `brp-mcp` to your MCP configuration file (`.mcp.json` or `claude_desktop_config.json`). 

We highly recommend using `uvx` to handle automatic installation and execution.

### Example Configuration (Remote hosted SSE)

If you are connecting to a centrally hosted server via SSE, use `npx` with the official proxy:

```json
{
  "mcpServers": {
    "brp_mcp_server": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/proxy",
        "https://dev-app.lanternbrp.com/brp-mcp-server/sse"
      ],
      "env": {
        "BRP_AUTH0_DOMAIN": "YOUR_AUTH0_DOMAIN",
        "BRP_AUTH0_CLIENT_ID": "YOUR_CLIENT_ID",
        "BRP_AUTH0_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

---

## Environment Variables

The server relies on environment variables for configuration. Here are the most commonly used ones:

| Variable | Default | Description |
|---|---|---|
| `BRP_ENV` | `dev` | Target API environment: `dev`, `stage`, `prod` |
| `BRP_TRANSPORT` | `stdio` | Transport mode: `stdio` (for AI agents) or `sse` (for web clients) |
| `BRP_AUTH0_DOMAIN` | *(empty)* | Auth0 tenant domain for API authentication |
| `BRP_AUTH0_CLIENT_ID` | *(empty)* | Auth0 Machine-to-Machine client ID |
| `BRP_AUTH0_CLIENT_SECRET` | *(empty)* | Auth0 Machine-to-Machine client secret |
| `BRP_API_TOKEN` | *(empty)* | Optional: Static bearer token fallback if not using Auth0 credentials |
| `BRP_HOST` | `0.0.0.0` | Bind host (used in `sse` mode) |
| `BRP_PORT` | `6010` | Port (used in `sse` mode) |

---

## Running as a standalone SSE server

If you want to host the server to be consumed by remote clients via Server-Sent Events (SSE):

```bash
export BRP_ENV=dev
export BRP_TRANSPORT=sse
export BRP_PORT=6015

uvx brp-mcp
```

The server will be available at `http://localhost:6015/sse`.
