Production MCP endpoint
https://mcp.fbplot.com/mcpTransport: Streamable HTTP; OAuth 2.1 Authorization Code + PKCE; protocol negotiation supported.
| Tool | Purpose | Scopes | Limits |
|---|---|---|---|
| resolve_players | Turn names into stable IDs | players:read | 30/min |
| search_players | Discover and filter players | players:read + stats:read | 30/min; 50/page |
| get_player_stats | Read selected metrics | players:read + stats:read | 60/min; 5 players; 250 cells |
| get_fbplot_capabilities | Read coverage and limits | players:read | 60/min |
| list_metrics | Discover valid metric IDs | stats:read | 60/min; 50/page |
| list_chart_presets | Discover chart/style presets | charts:read | 60/min; 50/page |
| create_chart | Create a private website-parity PNG inline | players:read + stats:read + charts:create | 5 renders/min |
| get_chart | Retrieve private chart metadata/PNG inline | charts:read | 60/min |
Availability: every tool requires an active FBPlot Pro subscription or Admin account, plus the scopes listed above. Entitlement is checked again at execution time.
resolve_players
See examples- When to use
- Use first when the user gives a name and you need a stable FBPlot player_id.
- Inputs
- name; optional season, competition_id, team_id, and limit (1-10).
- Output
- Bounded candidates with stable IDs and identity context. Inspect ambiguous candidates before continuing.
- Errors
- PLAYER_NOT_FOUND, AMBIGUOUS_PLAYER, INVALID_INPUT.
Example input
{ "name": "Lamine Yamal", "season": "2025/2026", "limit": 5 }search_players
See examples- When to use
- Use for bounded discovery, filtering, or ranking within one season.
- Inputs
- season plus optional query, teams, competitions, positions, nationality, age, minutes, and metric conditions.
- Output
- A paginated result set and the applied filters. It does not expose the full player dataset.
- Errors
- QUERY_TOO_COMPLEX, METRIC_NOT_AVAILABLE, SEASON_NOT_AVAILABLE, COMPETITION_NOT_AVAILABLE.
Example input
{ "season": "2025/2026", "position_categories": ["Forwards"], "minutes_min": 900, "page_size": 10 }get_player_stats
See examples- When to use
- Use after player IDs are confirmed and the requested metrics are known.
- Inputs
- 1-5 player_ids, up to 3 seasons, up to 3 competitions, aggregation, 1-16 metric_ids, normalization, and percentile preference.
- Output
- Only the requested statistics, definitions, coverage, and optional percentile fields.
- Errors
- PLAYER_NOT_FOUND, METRIC_NOT_AVAILABLE, INVALID_COMPARISON, QUERY_TOO_COMPLEX.
Example input
{ "player_ids": ["PLAYER_ID"], "seasons": ["2025/2026"], "aggregation": "season_total", "metric_ids": ["goals"], "normalization": "per90" }get_fbplot_capabilities
See examples- When to use
- Use at the beginning of a new workflow to discover coverage, chart limits, and supported modes.
- Inputs
- No arguments.
- Output
- Protocol version, entitlement rule, data freshness, supported chart types, limits, and privacy policy.
- Errors
- TEMPORARY_DATA_SERVICE_FAILURE.
Example input
{}list_metrics
See examples- When to use
- Use before guessing a metric ID or building a search, stats request, or chart.
- Inputs
- Optional search, category, chart_type, page, and page_size (1-50).
- Output
- Metric IDs, labels, units, categories, definitions, and supported chart/normalization modes.
- Errors
- METRIC_NOT_AVAILABLE, QUERY_TOO_COMPLEX.
Example input
{ "search": "progressive", "chart_type": "radar", "page_size": 20 }list_chart_presets
See examples- When to use
- Use to discover supported radar, bar, pizza, scatterplot, swarm, bubble, and visual-style preset IDs before create_chart.
- Inputs
- Optional chart_type, search, page, and page_size (1-50).
- Output
- Compact preset metadata and the metrics/styles each preset supports.
- Errors
- INVALID_COMPARISON, QUERY_TOO_COMPLEX.
Example input
{ "chart_type": "radar" }create_chart
See examples- When to use
- Use after identities and metrics have been confirmed and the user explicitly wants a saved visualization.
- Inputs
- radar, bar, pizza, scatterplot, swarm, or bubble chart_type, bounded player-season series, metrics, normalization, aspect ratio, style, branding, and optional customization.<chart_type> controls.
- Output
- Private chart_id, edit_url, metadata, data freshness, and the PNG as an inline MCP image block. No PNG URL or public share URL is created.
- Errors
- INVALID_COMPARISON, PLAYER_NOT_FOUND, METRIC_NOT_AVAILABLE, CHART_RENDER_FAILED, RATE_LIMITED.
Example input
{ "chart_type": "scatterplot", "series": [{ "player_id": "PLAYER_ID_1", "season": "2025/2026" }, { "player_id": "PLAYER_ID_2", "season": "2025/2026" }], "metric_ids": ["goals", "assists"], "radius_metric_id": "minutes" }get_chart
See examples- When to use
- Use to retrieve a previously created chart and its inline image while the stored asset is live.
- Inputs
- chart_id returned by create_chart.
- Output
- Owner-scoped chart metadata and the stored PNG as an inline MCP image block when it has not expired.
- Errors
- CHART_NOT_FOUND, INSUFFICIENT_SCOPE.
Example input
{ "chart_id": 123 }Annotations and chart contract
Read tools are marked read-only and idempotent. create_chart is state-changing and is intentionally not marked read-only; it creates a private saved chart and consumes a render quota.
create_chart supports radar (2-3 player-season series, 3-16 metrics), bar (one player-season series, 1-20 metrics), pizza (one player-season series, 3-16 metrics), scatterplot (2-50 player-season series, exactly two axis metrics, plus an optional radius metric), swarm (1-50 player-season series, up to 20 metrics), and bubble (2-50 player-season series, exactly two axis metrics, plus an optional radius metric). Metrics, seasons, and competitions are validated against the FBPlot catalogue and data coverage.
Chart customization parity
Use customization.<chart_type> to control the same visual settings that are rendered by the FBPlot editor. The MCP and website use the same chart preview and export root, so the PNG keeps the selected layout, colours, typography and branding.
{
"chart_type": "bar",
"series": [{ "player_id": "PLAYER_ID", "season": "2025/2026" }],
"metric_ids": ["goals", "assists", "shots"],
"customization": {
"bar": {
"compared_against": "Forwards",
"comparison_scope": "Top 5 leagues",
"stats_filters": { "minutes_min": 900 },
"background_color": "#f7faf9",
"bar_colors": { "attacking": "#c3552b" },
"player_name_font_family": "'Oswald', 'Helvetica Neue', sans-serif",
"label_font_size": 13,
"label_font_weight": 700,
"label_font_color": "#10272a"
}
}
}| Chart | Controls available through MCP |
|---|---|
| radar | Comparison cohort and filters; focused series; overlay/difference mode; metric order, value labels, precision, percentile format, radial scale and direction; canvas, grid, axes, metric-label typography, legend, header, photos, badges, flags and per-series fill/stroke/marker styles. |
| bar | Comparison cohort and filters; metric order; player evolution; palette; background and category colours; player, club, context and axis-label typography. |
| pizza | Comparison cohort and filters; metric order; player evolution; background and category colours; player, club and context typography; circular stroke, group gap and circular-label typography. |
| scatterplot | Comparison cohort and filters; axis labels and tick density; background, grid and average lines; title/subtitle/credit typography; bubble size, opacity, stroke, display mode, colour mode, league/position/metric/highlight colours, evolution and label placement/offsets. |
| swarm | Comparison cohort and filters; background and credit; row height, margins, circle radius, jitter, fill/stroke/opacity, logo mode, highlight colours, row/column axes, metric labels and highlighted-player labels. |
| bubble | Comparison cohort and filters; grid, links, trend and median toggles; X/Y labels and number/percent/custom axes; radius, logos, labels, label backgrounds, regions, quadrants, padding, dimensions, theme typography, links and league colours. |
Contract limits: fields are strict and bounded; colours must be hexadecimal; fonts must be certified FBPlot chart fonts; arbitrary CSS, HTML, external images and renderer options are rejected. MCP chart data is currently explicit player-season series. Website-only period modes such as last 365 days and custom dates are not silently simulated.