Stop guessing whether your dashboard JSON is right. Ask.
### Claude Desktop
Download `dashboardbase-mcp.mcpb` from the [latest release](https://github.com/dashboardbase/mcp/releases/latest) 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:
```json
{
"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:
```json
{
"servers": {
"dashboardbase": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@dashboardbase/mcp"]
}
}
}
```
### Codex CLI
Codex uses TOML. Easiest is the CLI:
```bash
codex mcp add dashboardbase -- npx -y @dashboardbase/mcp
```
Or by hand in `~/.codex/config.toml`:
```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.
| How you installed | How you update |
| --- | --- |
| `npx` (Claude Code, Cursor, VS Code, Windsurf, Codex) | Automatic — restart your client and the next server start picks up the newest version. |
| Claude Desktop `.mcpb` | Pinned at install. Download the new bundle from [releases](https://github.com/dashboardbase/mcp/releases/latest) and drag it in again. |
| Docker | `docker pull` / rebuild the image. |
Check what you're running:
```bash
npx -y @dashboardbase/mcp --version
```
If that reports an older version than [the latest release](https://github.com/dashboardbase/mcp/releases/latest), npm is serving cached registry metadata — a just-published version can take a few minutes to show up. Force it:
```bash
npx -y @dashboardbase/mcp@latest --version
```
Releases follow [semver](https://semver.org): new tools are a minor bump and never break existing calls, so updating is safe by default.
---
## Using it
### First, check it's connected
```bash
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
| Tool | Arguments | Notes |
| --- | --- | --- |
| `validate_setup_file` | `content` — the file text