fusebase-dashboards

name

fusebase-dashboards

description

How to use MCP for working with Fusebase dashboards during LLM development. Use when: 1. Discovering dashboards, views, schema via MCP; 2. Creating or updating dashboards/views; 3. Reading/writing dashboard data; 4. Working with relations, filters, templates, child tables; 5. Working with managed databases (e.g. meetings, companies, deals) — load prompts_search({ groups: ["managedDatabases"] }) and see references/meetings.md, references/companies.md, references/deals.md.

Fusebase Dashboards MCP Skill

This document describes how to use MCP (Model Context Protocol) for working with Fusebase dashboards during LLM development. MCP is used for discovery and execution from the LLM; the SDK is used only in runtime code (feature/browser). See the Fusebase Dashboards SDK skill for SDK usage.

For rules and checklists, see AGENTS.md.

• For runtime SDK code that reads or writes dashboard data (getDashboardViewData, batchPutDashboardData, etc.), references/data-patterns.md is required — it defines the real response/request shapes; use it together with sdk_describe (do not infer data.rows vs top-level data from memory).

---

References

Each reference is in a separate file under references/. Load the file when you need that topic.

meta

• Authorization and Scopes
• Bootstrap
• SDK Discovery
• Tooling

core

• Dashboard Data
• Dashboard Schema
• Domain Overview

specialized

• Child Tables
• Companies (managed database)
• Dashboard Relations
• Dashboard Rows
• Dashboard View Filters
• Dashboard View Representations
• Deals (managed database)
• Meetings (managed database)
• Templates

---

Mandatory: verify fusebase-dashboards MCP connection

Before any work with dashboards, the LLM must verify that the fusebase-dashboards MCP server is connected and available.

1. Check that MCP tools from the fusebase-dashboards server are present in your tool list (e.g. tools_list, tools_search, tool_call, bootstrap, prompts_list, prompts_search).
2. If fusebase-dashboards is not available (tools are missing or calls fail):
   • Stop and inform the user that the fusebase-dashboards MCP connection is required for working with dashboards.
   • Suggest that the user check their connected MCP servers in the IDE settings and ensure fusebase-dashboards is added and enabled.
   • For config (.env, MCP config files, fusebase init), see AGENTS.md or the mcp/ directory.
   • Do not proceed with dashboard operations until the connection is available.

MCP is for development and dashboard access from the LLM. SDK is only for runtime code in the feature.

---

MCP vs SDK (reminder)

• MCP tools (tools_list, tools_search, tools_describe, tool_call, bootstrap, prompts_list, prompts_search, etc.) — for performing actions inside the LLM session: discovery, reading/writing data, creating/updating dashboards during development.
• SDK methods — for runtime code only (feature/browser). The LLM uses sdk_search / sdk_describe to generate code that the feature will execute; the LLM does not execute SDK.

Do not mix: use either the MCP chain (discovery → tool_call) for development, or the SDK chain (sdk_search → sdk_describe → insert code) for generating feature code. Each operation has the same opId in both MCP and SDK.

---

Part I — Bootstrap and connection context

Right after session initialization, obtain the connection context: who is authenticated, which scopes/permissions apply, and what default arguments to use for tool calls.

Preferred path (if the client supports MCP Resources)

1. Read the resource resource://connection/context.
2. From the response, use: auth, defaults.toolArgs (scope_type, scope_id), usage, capabilities.

Alternative (tools only)

1. Call the bootstrap tool (no arguments).
2. In the response: connectionContextUri, whoamiToolName, defaults, usage, pointers (tool names for resources_list, resources_get, prompts_list, prompts_search).
3. If full JSON context is needed — call whoami (returns the same data as the connection/context resource).

Defaults rule

• If a tool call requires scope_type and scope_id and the LLM did not provide them — use values from defaults.toolArgs in the connection context.
• Explicitly passed arguments always take precedence over defaults.
• For database/dashboard operations, org scope is used by default: scope_type: "org", scope_id from context.

---

Part II — Tooling flow (when connection exists)

After the connection is established (session ID set, connection context loaded): have domain knowledge (prompts or skill in context), discover operations, get schemas, execute via tool_call.

II.1 Domain knowledge before domain tool calls

You must have the required domain knowledge (database, dashboard, view, relations, rows, data, etc.) before any domain tool calls. Two options:

Option A — Skill in context (when the project has this skill):

• If the project has the fusebase-dashboards skill (this document and references/*.md, generated from MCP prompts), ensure that skill is in this chat's context.
• Then you do not need to load prompts via MCP.

Option B — Load prompts via MCP:

• Always use a group filter when loading prompts.
• Never call prompts_search({}) or omit the groups parameter.
• Call prompts_search with groups: e.g. prompts_search({ groups: ["data", "rows", "schema"] }) for default dashboard work; add "dashboard", "filters", "templates", "relations", "childTables" when needed (see table below).
• If the result is too large, request one group at a time (e.g. ["schema"] then ["dashboard"]).

Invariant: Do not call domain operations until you have this knowledge (from the skill in context or from prompts).

Prompt groups (summary):

Group	Purpose
tooling	Discovery and execution (tools.list → describe → call)
authz	Permissions, scopes, ID formats
bootstrap	Connection context and defaults
database	Database entities and operations
dashboard	Dashboards, types, root_entity
view	Views (dashboard projections)
schema	Dashboard schema and columns
relations	one_to_many, many_to_many relations
filters	View filters
representations	Cell display
rows	Rows (custom rows)
data	Reading/writing cell data
templates	Templates and creating from templates
childTables	Child-table-link columns, get-or-create child dashboard
managedDatabases	Managed DBs (meetings, companies, deals: getOrCreate, aliases, relations)

II.1a Prompts and skills (version check)

The MCP server is the source of truth for prompt content. The skill folder fusebase-dashboards (e.g. in .claude/skills/ or generated/claude_skills/) contains the entrypoint and versioned reference files for IDE/agent loading.

Version check without loading full prompt bodies:

1. Get versions — Call prompts_list once. It returns for each prompt: name, title, description, groups, and version (semver). No message bodies; lightweight.
2. Compare with skills — Each skill's frontmatter has mcp_prompt (e.g. domain.childTables) and last_synced (date). Match by mcp_prompt to the list entry; compare version or regeneration date to see if the skill is up to date.
3. When to load the prompt — Use prompts_search (or native get_prompt) only when you need the actual content (e.g. by groups or by name). If operations fail or the skill is stale, the VERSION CHECK block in that skill's SKILL.md says: load MCP prompt {mcp_prompt} for latest content.

Rule: Use prompts_list for version checks; use prompts_search only when you need prompt text.

Why: Version checks stay cheap: less data over the network (no full prompt bodies) and fewer tokens used. Load full prompt content only when you actually need it.

---

II.2 Operation discovery

Operations cannot be guessed by name or REST path. Explicit discovery is required.

Step 1 — catalog or search:

• tools_list — full list of available operations (short descriptions, no full schemas).
• tools_search — search by keywords. Example: tools_search({ queries: ["create", "database"] }) or tools_search({ queries: ["getDashboardView", "view"] }).

Use the exact names returned by tools_list / tools_search.

Step 2 — operation schema:

• Call tools_describe with the operation name (as in the list/search result):
  • tools_describe({ name: "<op name>" }) — returns a compact input schema by default.
  • For data operations (e.g. batchPutDashboardData) prefer: tools_describe({ name: "batchPutDashboardData", schemaMode: "summary" }) — faster and sufficient for most cases.
  • schemaMode: "input" (default), "output", "both", "summary", "full". Use "full" only when needed (large payload).

Response includes: inputSchema, outputSchema, schemaVersion, requiredPrompts (groups/names), and promptsInvariant — reminder to have the required knowledge (from prompts or from this skill in context) before using the tool.

Step 3 — execution:

• All domain (business) operations must be executed only via tool_call.
• Direct invocation by tool name is allowed only for meta/built-in tools explicitly listed in the tools_list response (e.g. bootstrap, whoami, ping, tools_list, tools_search, tools_describe, tool_call, generate_id, prompts_list, prompts_search, resources_list, resources_get). Do not guess or call unknown operations by name — use tool_call only.

---

II.3 Executing operations

Universal way for domain operations:

tool_call({
  "opId": "<exact name from tools_list/tools_search>",
  "args": { ... }
})

Optional:

• schemaVersion — if provided and it does not match the server's current schema version, the server returns SCHEMA_VERSION_MISMATCH; then call tools_describe again and retry tool_call once with updated arguments.

Response format (for both tool_call and direct built-in calls):

• ok: boolean
• opId: string
• data?: unknown — on success
• error?: { message, code?, issues? } — on error

Rules:

1. By default always use tool_call to execute domain operations.
2. Direct calls only when the tool is registered (from tools_list) and is a meta/built-in tool.
3. Do not construct REST URLs from feature names; always rely on discovery (tools_list → tools_describe → tool_call) or the SDK.
4. When creating entities (dashboard, view, row, etc.) use generate_id when needed (format: uuid for global_id, nanoid for short keys/aliases).

---

II.4 Working with schemas

• In the tools_describe response, schemas may contain $ref like #/$defs/SomeName.
• $defs live in the same schema object (inputSchema or outputSchema) where the $ref is used.
• Resolve $ref by looking up the key in $defs of that same schema. Do not use external or absolute $ref values.
• For data operations prefer schemaMode: "summary"; if validation fails, request a more complete schema (input or full) if needed.

---

II.5 Error handling and retry

• TOOL_NOT_FOUND — operation is not in the allowed list; do not retry the same opId.
• SCHEMA_VERSION_MISMATCH — refresh the schema via tools_describe once and retry tool_call with correct arguments.
• INVALID_ARGS — response may include issues (validation details). Fix arguments per schema and retry.
• EXECUTION_FAILED — error on the API side; message in error.message. Do not retry automatically without changing the request.
• Authorization errors (access outside the token's scope) — do not retry; explain the access limitation to the user.

---

II.6 MCP vs SDK (in flow)

• MCP tools — for performing actions inside the LLM session (discovery, tool_call for dashboards/data).
• SDK methods — for application/runtime code only. Use sdk_search / sdk_describe when you need to generate code for the feature; same opId and input schema as the MCP tool.

Do not mix in one scenario: either the MCP chain (discovery → tool_call) or the SDK chain (sdk_search → sdk_describe → code generation).

---

II.7 Flow diagram summary

Tooling flow after the connection is established:

                    ┌──────────────────────────────────────────────────────────┐
                    │              LLM / MCP Client (session ready)             │
                    └──────────────────────────────────────────────────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │ 1. Bootstrap (if not done in Part I)               │
                    │    • resource://connection/context  OR             │
                    │    • bootstrap()  → then whoami if needed           │
                    │    • Remember defaults.toolArgs (scope_type, id)    │
                    └─────────────────────────┬───────────────────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │ 2. Have domain knowledge (before domain calls)       │
                    │    prompts_search({ groups: [...] }) OR skill in ctx  │
                    └─────────────────────────┬───────────────────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │ 3. Discovery                                        │
                    │    tools_search(queries: [...])  or tools_list()    │
                    │    → pick op by name from response                  │
                    └─────────────────────────┬───────────────────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │ 4. Operation schema                                 │
                    │    tools_describe({ name: "<op>", schemaMode? })    │
                    │    • data ops: schemaMode: "summary"               │
                    │    • Resolve $ref from $defs in same schema        │
                    │    • Honor requiredPrompts / promptsInvariant       │
                    │      (knowledge from prompts or skill in context)    │
                    └─────────────────────────┬───────────────────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │ 5. Execution                                       │
                    │    tool_call({ opId: "<name>", args: {...} })       │
                    │    • scope_type/scope_id from defaults when needed │
                    │    • On SCHEMA_VERSION_MISMATCH: describe + retry   │
                    └─────────────────────────┬───────────────────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │ 6. Handle response                                 │
                    │    ok ? data : error (message, code, issues)      │
                    └───────────────────────────────────────────────────┘

Short checklist (Part II, connection already exists):

1. Get context if needed (resource connection/context or bootstrap + whoami).
2. Have domain knowledge: load prompts (with groups) or ensure fusebase-dashboards skill is in chat context.
3. Find operations via tools_search or tools_list.
4. For each operation used — tools_describe (use summary for data ops).
5. Execute domain operations only via tool_call.
6. Handle errors by code (including schema version mismatch with one retry after describe).

---

Summary

• MCP = LLM development: used for discovery and dashboard access from the LLM; configure fusebase-dashboards in your IDE and verify connection before use.
• SDK = runtime only: used only in feature code; see the Fusebase Dashboards SDK skill.
• Connection check: Always verify fusebase-dashboards MCP is connected; if not, ask the user to check connected MCP servers.
• Flow: Bootstrap/context → have domain knowledge (prompts or skill in context) → tools_search/tools_list → tools_describe → tool_call → handle response.