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 |
| list_chart_styles | Browse UI graphic style presets | charts:read | 60/min; 50/page |
| get_chart_style | Read a complete graphic style | charts:read | 60/min |
| get_chart_style_options | Inspect style options and fonts | charts:read | 60/min |
| create_chart_style | Save a reusable graphic style | presets:write | 10/min |
| update_chart_style | Edit or rename a graphic style | presets:write | 20/min |
| delete_chart_style | Delete a graphic style | presets:write | 10/min |
| 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, detailed positions, market value, contract end, 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" }list_chart_styles
See examples- When to use
- Browse the same owned, public, default and built-in graphic presets as the UI. These are separate from metric presets.
- Inputs
- Optional chart_type, search, page and page_size (1-50).
- Output
- Style IDs and compact metadata; use get_chart_style for the payload.
- Errors
- INSUFFICIENT_SCOPE.
Example input
{ "chart_type": "radar" }get_chart_style
See examples- When to use
- Inspect a visible preset before applying it or copying its settings.
- Inputs
- style_preset_id from list_chart_styles.
- Output
- Complete native UI camelCase payload.
- Errors
- INVALID_COMPARISON, INSUFFICIENT_SCOPE.
Example input
{ "style_preset_id": "builtin:clean-comparison" }get_chart_style_options
See examples- When to use
- Discover available controls and certified font values before designing a style.
- Inputs
- chart_type.
- Output
- Supported native fields, customization JSON Schema, fonts and precedence rules.
- Errors
- INSUFFICIENT_SCOPE.
Example input
{ "chart_type": "bar" }create_chart_style
See examples- When to use
- Save a reusable graphic style after user approval. Requires the presets:write scope; reconnect an older grant to approve it.
- Inputs
- name, chart_type, payload in native UI camelCase. Public/default flags are Admin only.
- Output
- Saved preset ID and payload, available in the UI immediately.
- Errors
- INVALID_COMPARISON, INSUFFICIENT_SCOPE, RATE_LIMITED.
Example input
{ "name": "My editorial style", "chart_type": "bar", "payload": { "backgroundColor": "#ffffff", "labelFontSize": 14 } }update_chart_style
See examples- When to use
- Rename or replace an owned preset after user approval. Read its current payload first; payload replaces all settings.
- Inputs
- style_preset_id and at least one field to change.
- Output
- Updated preset. Existing chart PNGs remain unchanged.
- Errors
- INVALID_COMPARISON, INSUFFICIENT_SCOPE, RATE_LIMITED.
Example input
{ "style_preset_id": "123", "name": "Renamed style" }delete_chart_style
See examples- When to use
- Delete an owned preset after explicit user approval.
- Inputs
- style_preset_id.
- Output
- Deletion confirmation. Existing charts remain available.
- Errors
- INVALID_COMPARISON, INSUFFICIENT_SCOPE, RATE_LIMITED.
Example input
{ "style_preset_id": "123" }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_preset_id, native UI style overrides, branding, and optional customization.<chart_type> controls. Explicit fields/customization override the preset.
- 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.