BrightBean docs

MCP client setup

The BrightBean MCP server lives at https://api.brightbean.xyz/mcp and speaks the standard MCP streamable HTTP transport. Below are the most common client configs.

Claude Desktop

Claude connects to BrightBean two ways. The custom connector is the simplest — Claude signs you in through your browser, with no config file and no API key to paste. The mcp-remote bridge is for Claude Code or anyone who prefers the config file.

  1. In Claude Desktop, open Settings → Connectors and click Add custom connector.
  2. Give it a name (e.g. BrightBean), paste the server URL https://api.brightbean.xyz/mcp, and click Add.
  3. Claude opens a BrightBean sign-in window — log in (or create an account) and approve access.
  4. Once the connector shows as connected, the six BrightBean tools are available.

This path uses OAuth, so there is no API key to copy. Tool calls draw credits from the BrightBean account you sign in with, and the same connector works in Claude on the web and on mobile.

mcp-remote bridge (config file / Claude Code)

Claude Desktop’s config file launches local MCP servers only, so it reaches a hosted server through the mcp-remote bridge — a small local proxy that forwards to the server and attaches your key. Install Node.js first (mcp-remote runs via npx).

1. Open the config file. From the Claude menu → Settings… → Developer tab, click Edit Config. This reveals claude_desktop_config.json in Finder (macOS) or File Explorer (Windows) — it does not open an editor or a file picker. Open that file yourself in a text editor:

2. Add the brightbean server under mcpServers. If the file is empty, paste the whole block; otherwise merge the brightbean entry alongside any servers already there.

{
  "mcpServers": {
    "brightbean": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.brightbean.xyz/mcp",
        "--header",
        "Authorization:${BRIGHTBEAN_KEY}"
      ],
      "env": {
        "BRIGHTBEAN_KEY": "Bearer bb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

The key goes in env (not inline in --header) because mcp-remote mis-parses a --header value that contains a space.

3. Restart Claude Desktop. Fully quit (Cmd+Q) and reopen it. The six BrightBean tools appear under the MCP tools control next to the message box.

Cursor

Cursor connects to remote MCP servers natively — no bridge needed. Configuration lives in an mcp.json file: ~/.cursor/mcp.json for every project, or .cursor/mcp.json in a repo root for one project.

In Cursor → Settings → MCP (under Tools & Integrations), click New MCP Server — Cursor opens mcp.json for editing. Add:

{
  "mcpServers": {
    "brightbean": {
      "url": "https://api.brightbean.xyz/mcp",
      "headers": {
        "Authorization": "Bearer bb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Save the file; Cursor connects and lists the six BrightBean tools under the server’s toggle. To keep the key out of the file, use "Bearer ${env:BRIGHTBEAN_KEY}" and set BRIGHTBEAN_KEY in your environment.

Generic MCP client (LangChain, agent runtimes, custom)

The server is a standard MCP server — anything that speaks MCP over Streamable HTTP works. Set:

After the initial initialize handshake, tools/list will return the six BrightBean tools.

Verifying

Ask your client:

Use the brightbean tools to score the title “I bought a $0.99 keyboard so you don’t have to” with thumbnail https://i.ytimg.com/vi/EXAMPLE/hqdefault.jpg in the tech-reviews niche.

A working setup returns a score envelope with score_id and credits_remaining populated.

CORS is intentionally disabled

The MCP server does not send Access-Control-* headers. Calls from a browser will be blocked. MCP clients are expected to be server-side processes (or local desktop apps like Claude Desktop and Cursor), so this is by design — if you need a browser surface, use the REST API.

Troubleshooting