dashboardbase

dashboardbase MCP

Stop guessing whether your dashboard JSON is right. Ask.

This is the official MCP server for dashboardbase. Add it to your AI tool and it can check a widget endpoint's response — or a whole dashboard setup file — against the contract dashboardbase actually enforces, before you ever open the app.

The dashboardbase skill teaches your agent the JSON contract. This MCP lets it check its own work. Use both: the skill gets the shape right, the MCP proves it.

---

What this MCP does

It gives your agent three tools:

All three call the public dashboardbase tools API. No account, no API key, nothing to configure.

Before / after

Without it — your agent writes an endpoint, you deploy it, you wire it into dashboardbase, the widget shows an error, you go read the docs, you fix it, you deploy again.

With it — your agent writes the endpoint, validates the response, fixes the two things that were wrong, and hands you something that renders the first time.

Invalid setup file — 2 errors, 1 warning

mappings[0].type 14:9 Unknown widget type "guage" mappings[1].path 22:5 Path must start with "/"

warning mappings[2] No refreshInterval set

---

Install

Claude Code

claude mcp add dashboardbase -- npx -y @dashboardbase/mcp

One click

Claude Desktop

Download dashboardbase-mcp.mcpb from the latest release and drag it into Claude Desktop's extensions settings. The bundle is self-contained — you don't even need Node.

Cursor, Windsurf, and most other clients

These use the mcpServers shape. Add it to ~/.cursor/mcp.json (Cursor), ~/.codeium/windsurf/mcp_config.json (Windsurf), or your client's equivalent:

{

"mcpServers": { "dashboardbase": { "command": "npx", "args": ["-y", "@dashboardbase/mcp"] } } }

VS Code

VS Code is the exception — it uses servers rather than mcpServers, and requires an explicit type. In .vscode/mcp.json (workspace) or your user profile:

{

"servers": { "dashboardbase": { "type": "stdio", "command": "npx", "args": ["-y", "@dashboardbase/mcp"] } } }

Codex CLI

Codex uses TOML. Easiest is the CLI:

codex mcp add dashboardbase -- npx -y @dashboardbase/mcp

Or by hand in ~/.codex/config.toml:

[mcp_servers.dashboardbase]

command = "npx" args = ["-y", "@dashboardbase/mcp"]

Requires Node.js 20 or newer — that's the only prerequisite, and only for the npx routes. Nothing else to configure: the validation API is public, so there's no account, key or environment variable to set.

Staying up to date

Two different things arrive by two different routes, which is worth knowing:

Better error messages arrive on their own. The server holds no schemas — it calls the live API — so as validation messages improve, you see them immediately. Nothing to update.

New tools need a package update. If a release adds a tool, you get it once the package updates *and* your client restarts the server. A running server's tool list is fixed for the session.

Check what you're running:

npx -y @dashboardbase/mcp --version

If that reports an older version than the latest release, npm is serving cached registry metadata — a just-published version can take a few minutes to show up. Force it:

npx -y @dashboardbase/mcp@latest --version

Releases follow semver: new tools are a minor bump and never break existing calls, so updating is safe by default.

---

Using it

First, check it's connected

claude mcp list

You should see dashboardbase listed as connected. Inside a Claude Code session, /mcp shows the server and its three tools. In other clients, look for dashboardbase in the MCP or tools panel.

If it isn't there, the server never started — check that node --version is 20 or newer, and that your config file has valid JSON.

Then just ask

You don't call these tools yourself. Describe what you want and the agent decides to call them, the same way it decides to read a file. There's no special syntax and nothing to remember.

Validating something you already have:

• _"Validate my dashboardbase setup file"_
• _"Is .dashboardbase/revenue.json valid?"_
• _"Check this against the dashboardbase contract"_ — then paste the JSON

Validating as part of building:

• _"Build a KPI endpoint for MRR, then validate the response it returns"_
• _"Add a gauge widget to my setup file and make sure it still validates"_

Debugging something broken:

• _"My gauge widget shows an error in dashboardbase — check what my endpoint returns against the contract"_
• _"Why is dashboardbase rejecting my setup file?"_

What it looks like

You: My revenue widget isn't rendering. Check .dashboardbase/revenue.json.

Agent: *calls validate_setup_file*

`

Invalid setup file — 2 errors

mappings[0].type 14:9 Unknown widget type "guage"

mappings[1].path 22:5 Path must start with "/"

`

Agent: Two problems — guage is a typo for gauge, and the second mapping's

path is missing its leading slash. Fixing both now.

*edits the file, calls validate_setup_file again*

`

Valid setup file — no errors.

`

That loop — validate, fix, re-validate — is the whole point. The agent closes it without you opening dashboardbase.

Or invoke it directly

In Claude Code, the server adds a slash command — type / and it's in the menu:

/mcp__dashboardbase__validate .dashboardbase/revenue.json

Leave the path off and it validates whatever you're working on, or whatever you paste next. This is the deterministic route: it doesn't depend on the agent deciding the tool is relevant.

The middle segment comes from the name you installed under. If you ran claude mcp add dashboardbase … it's /mcp__dashboardbase__validate; install it as something else and that segment changes to match.

In clients that don't support MCP prompts, just name the tool in plain language:

• _"Use validate_setup_file on .dashboardbase/revenue.json"_
• _"Use validate_widget_response to check this"_

Agents sometimes need the nudge the first time; after that they usually pick it up on their own.

The three tools

| validate_setup_file | content — the file text path — read from disk instead | Give one or the other. | | validate_widget_response | response — the endpoint's JSON body path — read from disk instead widgetType — optional, e.g. kpi | Inferred from the response when widgetType is omitted. | | create_setup_link | content — the file text path — read from disk instead | The link expires after 48 hours and anyone holding it can read the file, so share it directly. |

Two things worth knowing:

• `path` only exists over stdio. A hosted HTTP deployment has no access to your disk, so the parameter isn't offered there — pass content / response instead.
• `validate_widget_response` wants the full response body — the title / actions / data / alert envelope your endpoint actually returns, not just the inner data payload.

Configuration

Everything is optional.

Running it as an HTTP server

For containers or a shared internal deployment:

npx @dashboardbase/mcp --http --port 3000

or

docker build -t dashboardbase-mcp . && docker run -p 3000:3000 dashboardbase-mcp

Serves Streamable HTTP at /mcp and a health check at /health. It's fully stateless, so it scales horizontally with no session affinity. Browser origins are refused unless you allowlist them with --allowed-origin https://example.com. The file-reading path parameter is not exposed in this mode.

---

What's in the repo

mcp/

├── src/ │ ├── index.ts # CLI entry — stdio by default, --http optional │ ├── server.ts # Registers the three tools │ ├── api.ts # Client for the dashboardbase Tools API │ ├── format.ts # Renders results as readable text │ ├── http.ts # Stateless Streamable HTTP handler │ └── tools/ # One file per tool ├── test/ # Unit tests, no network required ├── tools.json # OpenAPI spec for the validation API ├── server.json # MCP Registry manifest ├── manifest.json # Claude Desktop bundle manifest └── Dockerfile

How validation works

The server doesn't carry a copy of the schemas — it calls the live dashboardbase validation API. So it can't drift from what the platform accepts, and error messages get better as the API does, with nothing to upgrade on your side.

That applies to the validation rules and messages, not to the server itself — a release that adds a tool still needs a package update. See Staying up to date.

Related