MCP server

The BrightBean Model Context Protocol server makes every piece of BrightBean’s intelligence callable as a tool from any MCP-aware client — Claude Desktop, Cursor, generic LangChain-style agents, your own runtime.

Server details


URL	`https://api.brightbean.xyz/mcp`
Transport	Streamable HTTP
Auth	OAuth (native connectors) or the same bearer key as the REST API (`Authorization: Bearer bb_…`)
CORS	Disabled — MCP clients are expected to be server-side or desktop apps.

Tools

Six tools are exposed. Each one is a thin wrapper over a REST endpoint with an agent-friendlier response shape (see callout below).

score_packaging

Score a YouTube packaging (title and/or thumbnail) for predicted click-through rate. The server auto-detects mode from your inputs.

1 / 2 / 3 credits

score_video_hook

Analyze the first ~6 seconds of a YouTube video for hook quality. Returns archetype classification, five dimension scores, and concrete suggestions.

10 credits

research_content_gaps

Return ranked content opportunities for a YouTube niche.

5 credits

list_niches

List every catalogued YouTube niche for the active research run. Use the returned slugs as the niche argument to research_content_gaps.

1 credit

benchmark_channel

Benchmark a YouTube channel against its niche — engagement percentiles, title patterns, and exemplar channels.

5 credits

benchmark_video

Benchmark a single YouTube video against its niche.

3 credits

REST vs MCP response shape

MCP tool responses include two extra fields that the REST endpoint does not return:

score_id — an immutable identifier for the call, useful for client-side correlation and replay.
credits_remaining — your balance after this call. REST clients fetch the balance via GET /v1/usage/.

benchmark_channel and benchmark_video additionally wrap the response body under a payload field, so the envelope is {score_id, credits_remaining, payload}. The other tools merge the fields at the top level.

This is intentional. Tool-using agents typically want both pieces of state inline; HTTP clients usually do not.

Client setup

See Client setup for Claude Desktop, Cursor, and generic JSON-RPC client configuration.

Common patterns

Score then research — Ask the agent to score a draft packaging, then call list_niches + research_content_gaps for adjacent opportunities.
Benchmark before scoring — Run benchmark_channel first so the agent knows the playing field; then score variants against that baseline.
Loop on the score — Have the agent iterate on title variants until score_packaging returns a grade of A or above (or you run out of credits — set a budget).

Limits and quotas

The MCP surface shares your account’s rate limit and credit balance with the REST API. See Rate limits. MCP responses include credits_remaining inline so the agent can self-regulate.