LanternBRP MCP Server

MCP server that exposes LanternBRP Gateway APIs as AI-agent tools. Works with Cursor, Claude Desktop, and any MCP-compatible AI host.

Build & Publish (for maintainers)

cd brp_mcp_python_package/

# Install build tools (one-time)
pip install build twine

# Build the package
python -m build

# Upload to PyPI
twine upload dist/*

This creates dist/brp_mcp-<version>-py3-none-any.whl and dist/brp_mcp-<version>.tar.gz. After publishing, all users get the update via uvx --upgrade brp-mcp.

To bump the version before a release, edit version in pyproject.toml:

[project]
version = "0.2.1"

Quick Start (for AI-agent users)

Add this to your MCP config (e.g. Cursor's mcp.json or Claude Desktop's config):

{
  "brp_mcp_server": {
    "command": "uvx",
    "args": ["--upgrade", "brp-mcp"],
    "env": {
      "BRP_ENV": "dev",
      "BRP_AUTH0_CLIENT_ID": "<your-client-id>",
      "BRP_AUTH0_CLIENT_SECRET": "<your-client-secret>"
    }
  }
}

That's it. The server auto-resolves gateway URLs, Auth0 domain, audience, tool descriptions, and visibility from the bundled config based on BRP_ENV.

How It Works

AI Agent (Cursor / Claude Desktop)
    ↕  MCP Protocol (stdio)
brp-mcp server (local subprocess)
    ↕  HTTPS (Auth0 bearer token)
LanternBRP Gateway API

1. The AI host spawns brp-mcp as a child process via uvx
2. The server fetches the LanternBRP Gateway's OpenAPI spec over HTTP
3. It registers one MCP tool per visible API endpoint
4. Tool descriptions are enriched with N8N-style domain instructions
5. When the AI calls a tool, the server makes an authenticated HTTP request to the Gateway
6. Auth0 M2M tokens are obtained automatically using the provided client credentials

Bundled Config

All config files are shipped inside the Python package:

Config Resolution Priority

Each config value is resolved in this order (first match wins):

1. Environment variable      (BRP_OPENAPI_URL, BRP_AUTH0_DOMAIN, etc.)
2. CWD-relative .config/     (for local dev when running from project dir)
3. Bundled config in package  (ships with the PyPI wheel)
4. Hardcoded fallback         (safety net in source code)

Environment Variables

Required (in mcp.json env block)

Optional Overrides

Environment Profiles

How to Enhance (Add New API Endpoints)

When the LanternBRP Gateway adds new APIs, follow these steps to expose them as AI tools:

Step 1: Add tool description enrichment

Edit src/brp_mcp/bundled_config/n8n_description_enrichments.json:

{
  "GET /api/new-endpoint": {
    "n8n_node": "get New Endpoint",
    "description": "Describe what this tool does, its mandatory fields, validation rules, etc."
  },
  "POST /api/new-endpoint": {
    "n8n_node": "create New Endpoint",
    "description": "Creates a new record. Required fields: name, type."
  }
}

Key format: METHOD /api/path with {*} for path parameters (e.g. PUT /api/items/{*}).

Step 2: Add visibility entry

Edit src/brp_mcp/bundled_config/mcp_visibility_policy.json:

{
  "operations": {
    "GET /api/new-endpoint": true,
    "POST /api/new-endpoint": true
  }
}

Use {id}, {tenantId}, etc. for path parameters here (matching the OpenAPI spec format).

Step 3: Add hardcoded fallback

Edit src/brp_mcp/main.py and add entries to _INTERNAL_DEFAULT_VISIBLE_OPERATIONS:

_INTERNAL_DEFAULT_VISIBLE_OPERATIONS = {
    # ... existing entries ...
    "GET /api/new-endpoint",
    "POST /api/new-endpoint",
}

Step 4: Build and publish

See the Build & Publish section below.

How to Build the Package

Prerequisites

pip install build twine

Build

From inside the brp_mcp_python_package/ directory:

python -m build

This creates two files in dist/:

• brp_mcp-0.2.0-py3-none-any.whl — the wheel (binary distribution)
• brp_mcp-0.2.0.tar.gz — source distribution

Verify bundled configs are included

unzip -l dist/brp_mcp-*.whl | grep bundled_config

You should see all JSON and TXT files listed inside brp_mcp/bundled_config/.

How to Publish to PyPI

Test upload (recommended first time)

twine upload --repository testpypi dist/*

Verify with:

uvx --index-url https://test.pypi.org/simple/ brp-mcp --help

Production upload

twine upload dist/*

After upload, users get the new version automatically:

uvx --upgrade brp-mcp

Version bumping

Before building a new release, update the version in pyproject.toml:

[project]
version = "0.2.1"  # bump this

Local Development

Editable install

cd brp_mcp_python_package/
pip install -e .

Now brp-mcp runs from your local source. Changes to .py files take effect immediately.

Run from source

# Using the console script
brp-mcp

# Or directly
python src/brp_mcp/main.py

CWD overrides during development

When running from a directory that contains .config/, those files take priority over bundled configs. This lets you test enrichment/visibility changes without rebuilding the package:

your-project/
├── .config/
│   ├── n8n_description_enrichments.json   ← used instead of bundled
│   └── mcp_visibility_policy.json         ← used instead of bundled
└── ...

Troubleshooting

"BRP MCP startup failed: Failed to load remote spec"

The server couldn't reach the OpenAPI spec URL. Check:

• Network connectivity to the LanternBRP gateway
• BRP_ENV is set correctly
• If using URL overrides, verify BRP_OPENAPI_URL is correct

"Incomplete Auth0 configuration"

Missing credentials. Ensure your mcp.json includes:

• BRP_AUTH0_CLIENT_ID
• BRP_AUTH0_CLIENT_SECRET

Domain and audience are auto-resolved from BRP_ENV profile.

"Auth0 token exchange failed"

The credentials are wrong or the Auth0 application doesn't have the right permissions. Verify:

• Client ID and secret are correct for the target environment
• The Auth0 application has client_credentials grant enabled
• The audience matches the API identifier in Auth0

"Missing or invalid Authorization bearer token"

No authentication method succeeded. The server tried (in order):

1. HTTP headers from MCP context
2. OAuth access token from MCP context
3. Meta authorization from request context
4. BRP_API_TOKEN environment variable
5. Auth0 M2M client credentials

Ensure at least one method is configured.

Tools not appearing

Check visibility:

• The endpoint must exist in the OpenAPI spec
• It must be marked true in the enrichments, visibility policy, or internal allowlist
• Run with BRP_LOG_LEVEL=DEBUG to see which endpoints are filtered and why