Skip to main content
Glama
dashboardbase

dashboardbase

Official
by dashboardbase
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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:

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.

create_setup_link

Uploads a finished setup file and returns a link that opens straight into its import preview — only when you ask for one. Refuses a file carrying credentials and lists the offending fields.

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

Related MCP server: kube-lint-mcp

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.

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 and drag it in again.

Docker

docker pull / rebuild the image.

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

Tool

Arguments

Notes

validate_setup_file

content — the file textpath — read from disk instead

Give one or the other.

validate_widget_response

response — the endpoint's JSON bodypath — read from disk insteadwidgetType — optional, e.g. kpi

Inferred from the response when widgetType is omitted.

create_setup_link

content — the file textpath — 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.

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:

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

  • dashboardbase — the product. Build, host, and share dashboards from your APIs.

  • dashboardbase skill — free to install; teaches your agent the JSON contract so it writes correct endpoints in the first place. Pairs directly with this MCP.

  • Documentation — widget reference, JSON contract, webhook setup.

Contributing

Found a gap or a confusing error? Open an issue. Note that the validation rules themselves live in the dashboardbase backend — if a message is unclear that's still worth reporting here, and we'll fix it upstream.

License

MIT — see LICENSE. Fork it, adapt it, ship it.

The MIT license covers the code in this repo — not the dashboardbase name or logo, which belong to Kompile ApS. You're free to use and adapt the server; please don't use the name or branding in a way that implies official affiliation.

The dashboardbase skill is licensed differently: free to install and use, but not open source.

Available Tools

3 tools
validate_setup_fileValidate dashboardbase setup fileA
Read-only

Validate a dashboardbase setup file (the declarative JSON that provisions a dashboard, usually stored at .dashboardbase/.json). Returns whether the file is valid plus any errors and warnings, with the JSON path, field and line/column of each problem. Use this after writing or editing a setup file, before telling the user it is ready to import.

NameRequiredDescriptionDefault
pathNoPath to the file to validate, absolute or relative to the working directory.
contentNoThe full text of the setup file. Provide this or `path`.

Output Schema

NameRequiredDescription
validYesTrue when the setup file passes validation.
errorsYesProblems that make the file invalid.
warningsYesNon-fatal advice about the file.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond them: the return shape (valid flag plus errors and warnings) and the granularity of diagnostics (JSON path, field, line/column). It does not mention any limits or failure modes of the validator itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the front-loaded clause identifies the artifact before moving to returns and then usage timing. Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema already exists, so return values need no elaboration, yet the description still summarizes them in one clause for routing decisions. With full schema coverage, a clear usage trigger, and an explicit read-only annotation, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented in the schema, including the 'provide this or `path`' relationship. The description adds no parameter-level detail (e.g. precedence when both are supplied), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (validate) and resource (dashboardbase setup file), and defines the resource parenthetically as the declarative JSON provisioning a dashboard stored at .dashboardbase/<name>.json. That is enough for an agent to identify it, though it never names a sibling such as validate_widget_response, so differentiation relies on the agent noticing the distinct resource noun.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit timing: 'after writing or editing a setup file, before telling the user it is ready to import.' That is a clear usage context. It stops short of alternatives or exclusions (e.g. when to prefer validating by path vs. content), so it does not reach the top band.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_widget_responseValidate dashboardbase widget responseA
Read-only

Validate the JSON body a dashboardbase widget endpoint returns, against the widget contract. Pass the complete response body — the envelope with title, actions, data and alert — exactly as the endpoint returns it, not just the inner data payload. Returns whether the response is valid, the widget type it was checked against, and the path and message of each problem. Use this after building or changing an endpoint that dashboardbase will poll.

NameRequiredDescriptionDefault
pathNoPath to the file to validate, absolute or relative to the working directory.
responseNoThe full response body from the widget endpoint, including the title/actions/data/alert envelope. Accepts a JSON object or a JSON string. Provide this or `path`.
widgetTypeNoOptional widget type to check against, for example "kpi", "line" or "table". Inferred from the response when omitted.

Output Schema

NameRequiredDescription
validYesTrue when the response passes validation.
errorsYesProblems that make the response invalid.
widgetTypeNoThe widget type the response was validated against.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish this is a safe, read-only, open-world check, so the description only needs to add context — and it does: it warns that the FULL envelope must be passed rather than just the inner `data` payload, and notes the widget type is inferred when omitted. It does not discuss error semantics or partial validation, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then the critical input caveat, then usage context. Three sentences with little waste, though the sentence enumerating return fields is largely redundant given the output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no further explanation, and annotations cover the safety profile. Between the description's input-shape warning and the schema's 100% parameter coverage, an agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying the shape of the `response` argument (the title/actions/data/alert envelope, not the inner payload) and reinforcing that `widgetType` is optional and inferred — real semantic guidance rather than restatement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — validating a dashboardbase widget endpoint's JSON body against the widget contract — and names the artifact ('the envelope with title, actions, data and alert'), which distinguishes it from the sibling validate_setup_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear trigger: 'Use this after building or changing an endpoint that dashboardbase will poll.' That tells the agent when the tool applies, but it never names or rules out the sibling tools (validate_setup_file, create_setup_link), so the routing is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.1
    • Addedcreate_setup_link
  2. 2 tool updatesv1.0.0
    • First observedvalidate_setup_file
    • First observedvalidate_widget_response
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: validating a setup file, validating a widget endpoint response, and generating a share link. The two validation tools could superficially overlap, but their descriptions sharply delineate the different contracts (setup JSON vs. widget response envelope).

Naming Consistency5/5

All three tools follow a consistent verb_noun pattern (validate_setup_file, validate_widget_response, create_setup_link). Conventions are uniform and predictable.

Tool Count4/5

Three tools is on the lean side but each earns its place in a narrow validation-plus-linking scope. Nothing feels redundant, though the surface is thin enough that it sits near the borderline.

Completeness4/5

The validate-then-share lifecycle is well covered, including a safety guard on credential-shaped fields in the link tool. Minor gaps exist (e.g. no way to fetch the widget contract or read an existing setup file), but they are workable around the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers