MCP · agents

Use VoxelBench from your agent

One endpoint, the tools of the API, and a diagnosis already computed. Your agent reads measurements and looks after your servers — it never produces a measurement, and never deletes anything.

Mint an API token API reference llms.txt

Claude Code — one command

Add the server — no token to create:

bash

claude mcp add --transport http voxelbench https://voxelbench.com/api/v1/mcp

Then type /mcp in Claude Code, pick voxelbench and choose Authenticate. Your browser opens the same consent page as Claude Web: you approve exactly what it may read and change, and Claude Code renews its access on its own.

For scripts and CI, where nobody is there to click

Mint a token, tick only the scopes you need, then run this. The token travels with every request; nothing is stored on our side.

bash

claude mcp add --transport http voxelbench https://voxelbench.com/api/v1/mcp \
  --header "Authorization: Bearer vb_your_token"

Or write it yourself, in .mcp.json for the project or ~/.claude.json for your account:

.mcp.json

{
  "mcpServers": {
    "voxelbench": {
      "type": "http",
      "url": "https://voxelbench.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer vb_your_token" }
    }
  }
}

Your agent then sees what your account sees: your private reports, your servers, your runs.

Claude Web and Desktop — a custom connector

Settings → Connectors → Add custom connector, then paste this URL. Claude will ask you to sign in and approve what it may read and change — no token to copy anywhere.

URL

https://voxelbench.com/api/v1/mcp

You approve it, on screen

The connector form takes only a URL, so the server answers with an authorization challenge: Claude opens a VoxelBench page that names the application, where it will send you back, and exactly what it asks for. Approve, and it reads your own data — private reports included. The grant is one of your plan's API tokens and shows up alongside them, to revoke whenever you want.

What your agent can do

This list is the server's own catalogue — the tools every account can use, loaded by both transports, so it cannot drift from what is actually served.

list_reports
Lists readable benchmark reports.
get_report
A full report: scores, sub-scores, multipliers, hardware.
compare_servers
Compares two benchmark reports - one report is one measurement of one server - and returns a verdict that is ALREADY COMPUTED server-side.
get_report_diagnosis
Named findings for a report: what its measurements imply, each with a severity, the test concerned, a cause code when the payload settles one, and the numbers that produced it.
list_unit_tests
Lists unit tests.
get_unit_test
A full unit test: percentiles, test-specific metrics, parameters, and for a tier run the rung-by-rung progression.
list_servers
Linked servers, with their verification state.
list_auto_bench_targets
The bearer's auto-bench targets.
list_auto_bench_jobs
Runs of the bearer's targets.
run_auto_bench_now
Triggers a run on an EXISTING target.
cancel_auto_bench_job
Asks a run to stop.
update_server
Renames a linked server or changes its visibility settings: name, is_public, show_address_on_report, notify_on_report.
link_server
Links a NEW Minecraft server to the account, using the 8-character code the VoxelBench plugin prints in the server console (/bench link).
list_server_groups
The account's server groups (20 at most).
create_server_group
Creates a server group.
update_server_group
Renames, recolours or reorders a server group.
set_server_group
Sorts a server into a group, or takes it out with group_id: null.
update_report
Changes a report's visibility, description or private notes.
list_alert_rules
The monitoring alert rules of one of the bearer's servers.
create_alert_rule
Creates a monitoring alert rule on a server: fire when metric is below/above threshold for duration_minutes.
update_alert_rule
Edits an alert rule, or pauses it with enabled: false.
get_maintenance
Whether one of the bearer's servers is in a maintenance window, until when and why.
start_maintenance
Starts a maintenance window on one of the bearer's servers for duration_minutes (REQUIRED, 5 to 1440): every alert of the server keeps being evaluated and recorded, but nobody is notified until the window ends - use it before a planned restart, an update or any work that would trip the alerts.
end_maintenance
Ends the maintenance window in progress on one of the bearer's servers: its alerts are notified again from the next evaluation (within a minute).
list_alert_events
Alerts the bearer's rules raised, most recent first, from BOTH families: threshold rules (kind: threshold) and event rules (kind: event, e.g.
list_event_alert_rules
The event alert rules of one of the bearer's servers, read-only: what event type, category, source and minimum severity each one matches, and on which channels it notifies.
test_alert_rule
Sends a TEST notification for a threshold alert rule now, on the channels the rule notifies (in-app, email, the server's Discord webhook, the owner's personal Discord), prefixed with [TEST], and returns what each channel did (delivery).
acknowledge_alert
Acknowledges a triggered alert: marks it seen and stops it from being notified again.
update_auto_bench_target
Reschedules an EXISTING auto-bench target: enabled (false pauses it), schedule_cron (five-field cron evaluated in UTC, at most once per hour - schedule_too_frequent otherwise), name, notes.
get_server_status
Live status of one of the bearer's servers (owned_by_you: true; another account's server answers not_owner).
get_server_regression
Whether a verified server's benchmark performance has dropped - the verdict the platform's regression alert computes, ALREADY DECIDED: quote it, do not recompute it.
get_monitoring_overview
The state of ALL the bearer's monitored servers in ONE call - use it instead of calling get_server_status once per server, which spends quota for each.
get_server_metrics
Time series of one of the bearer's servers (owned_by_you: true; another account's server answers not_owner) - the same data the dashboard charts.
list_server_events
The timeline of one of the bearer's servers (owned_by_you: true; another account's server answers not_owner), most recent first: starts, stops and restarts, benchmark runs, moderation actions, alerts raised by third-party plugins.
get_profile_history
The performance-profile history of one of the bearer's servers (owned_by_you: true; another account's server answers not_owner): one summary per profile the server sent, most recent upload first - who used the tick (owners, plugins included, self_pct and total_pct), the busiest methods, a breakdown by kind of work (categories) and key_points.
get_profile
One full performance profile of one of the bearer's servers (owned_by_you: true; another account's server answers not_owner), while the plan's limits still keep it: take profile_id from get_profile_history - null there means the profile is gone and only its summary is left (404 here).
compare_profiles
What changed between two performance profiles of the same server of the bearer (owned_by_you: true): shares per owner, per kind of work (categories) and per method, key points that appeared or were resolved.
list_profiles
The performance profiles of EVERY server the bearer owns, in one call, most recent upload first: one row per profile, read from its summary (kept a year) - server_id and server_name, trigger (manual, ring, lag), lag (kind, slow_ticks, longest_tick_ms), tick_samples, and top_plugin (the listed plugin with the largest own share of tick samples, with self_pct and total_pct).
list_memory_reports
Memory reports, most recent upload first: heap summaries (kind heap-summary, the JVM class histogram per plugin, shallow sizes) and heap dump analyses (kind heap-analysis: quick = shallow sizes by class loader, full = retained sizes and leak suspects, retained = a targeted analysis of ONE plugin: what that plugin alone retains, plus the quick-pass sections).
get_memory_report
One memory report of one of the bearer's servers (owned_by_you: true; another account's server answers not_owner), with a compact diagnosis: totals, memory per owner, leak suspects with their path from a GC root (path.steps, first step the root side; via is how the previous object holds the next, e.g.
compare_memory_reports
Compares two memory reports of the SAME server of the bearer (owned_by_you: true; another account's server answers not_owner; a report of another server is not_found).
get_report_tuning
Tuning advice computed from a report - exactly what its page shows.
compare_before_after
Did a change improve a server? Give the report ids from BEFORE and AFTER the change, and the subtests it targeted.
list_offers
Hosting offers with the evidence behind their performance: certified (hoster-approved, not expired), measured (VoxelBench ran the benchmark), linked (only associated), or none.

What to ask it

Once connected, plain language is enough.

« Open my latest report and tell me what its measurements imply. »
« Compare these two reports and tell me which host wins, and on what. »
« Launch a benchmark on my auto-bench target, then tell me when the report is in. »
« Show my auto-bench jobs from this week and tell me which ones failed, and why. »
« Link my new server with code K7PX2QMA, name it Survival 1.21 and put it in my Production group. »

What holds, whichever agent you use

• Every figure comes out of the benchmark pipeline. Comparisons and diagnoses are computed server-side and handed over already decided — the model quotes them, it does not recompute them.
• A resource you may not read answers 404, never 403. Your agent must not read that as "it does not exist".
• One tool call costs one read. Your plan's daily cap applies per account — not per token, so a second connector buys nothing. A run occupies its target: replaying a launch adopts the run already in flight instead of starting a second one.
• A token carries only the scopes you ticked, and never more than your current plan grants.