mcp

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="logo-light.png">
    <img src="logo-dark.png" width="180" alt="dashboardbase">
  </picture>
</p>

<h1 align="center">dashboardbase MCP</h1>

<p align="center">
  <strong>Stop guessing whether your dashboard JSON is right. Ask.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@dashboardbase/mcp"><img src="https://img.shields.io/npm/v/@dashboardbase/mcp?color=2563eb" alt="npm version"></a>
  <a href="https://registry.modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP%20Registry-com.dashboardbase%2Fmcp-2563eb" alt="MCP Registry"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e" alt="MIT License"></a>
  <a href="https://dashboardbase.com"><img src="https://img.shields.io/badge/dashboardbase.com-0a0a0a" alt="Dashboardbase"></a>
</p>

This is the official [MCP server](https://modelcontextprotocol.io) for [dashboardbase](https://dashboardbase.com). 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](https://github.com/dashboardbase/skills) 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 two tools:

| Tool | What it checks |
| --- | --- |
| `validate_setup_file` | A dashboardbase setup file — the JSON that provisions a whole dashboard's widgets and datasources. Reports errors and warnings with the field, line and column. |
| `validate_widget_response` | The JSON body a widget endpoint returns, against the widget contract. Reports the path and message for each problem. |

Both call the public dashboardbase validation 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

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

### One click

<a href="https://insiders.vscode.dev/redirect/mcp/install?name=dashboardbase&config=%7B%22name%22%3A%22dashboardbase%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40dashboardbase%2Fmcp%22%5D%7D"><img src="https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white" alt="Install in VS Code"></a>
<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=dashboardbase&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBkYXNoYm9hcmRiYXNlL21jcCJdfQ=="><img src="https://img.shields.io/badge/Cursor-Install-000000?logo=cursor&logoColor=white" alt="Install in Cursor"></a>

### 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 two 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 two tools

| Tool | Arguments | Notes |
| --- | --- | --- |
| `validate_setup_file` | `content` — the file text<br>`path` — read from disk instead | Give one or the other. |
| `validate_widget_response` | `response` — the endpoint's JSON body<br>`path` — read from disk instead<br>`widgetType` — optional, e.g. `kpi` | Inferred from the response when `widgetType` is omitted. |

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.

| Variable | Default | Purpose |
| --- | --- | --- |
| `DASHBOARDBASE_API_URL` | `https://api.dashboardbase.com` | Point at a different environment. |
| `DASHBOARDBASE_API_KEY` | _unset_ | Sent as `x-api-key`. Not needed for the public API. |
| `DASHBOARDBASE_TIMEOUT_MS` | `15000` | Request timeout in milliseconds. |

### Running it as an HTTP server

For containers or a shared internal deployment:

``