Reference

MCP server

Every environment of a hosted dabadata project can be an MCP server. Developers' agents (Claude Code, Cursor) use it with the secret key to build and debug the app; people use it inside ChatGPT and Claude, signed in as themselves, with the app's tables and forms drawn as live widgets in the conversation. A self-hosted server also has a local stdio server, at the end of this page.

The hosted MCP server

The address is https://dabadata.com/mcp/<project id> for live and https://dabadata.com/mcp/<project id>_test for test (on a self-hosted server, /mcp/<project name> for its default project). It speaks MCP over Streamable HTTP: JSON-RPC in a POST, answered as JSON, no session needed. Every call goes through the same rules, trace and usage as the HTTP API, with source: "mcp" in the trace.

Turn it on

The server is off until the definition has an mcp block with enabled: true (until then the address answers 404):

"mcp": {
  "enabled": true,
  "name": "Team expenses",
  "instructions": "Track shared expenses. Amounts are in euros.",
  "allowAnonymous": false,
  "tables": {
    "expenses": { "tools": ["list", "get", "create", "update"], "widget": "table", "describe": "One row per expense" }
  }
}

Without tables every declared table gets its default tools and no widget. Apply it like any definition change: a dry run, then PUT /v1/schema, the console's Definition page, or the agent's apply_definition. The console's Apps page shows whether it is on and adds the block for you.

Who connects, and with what

A key or token of another environment is refused (401); the address alone grants nothing. View tokens and refresh tokens are not accepted here.

Tools

A result carries the data as structuredContent ({ rows }, { row }) and as text. A denial is a tool error whose text is the rule's explanation, so the model can tell the person why, or fix the rule. Rows are shaped as on /v1: a column the caller may not read is left out, and a write answers { id } for a row the caller may not read.

Strict tables in the user toolset. A strict table (access: "views") has no <t>_* tools for end users: describe_app and the server's default instructions leave it out, the transact tool's table list does not offer it (an op naming it is refused with the 403 explanation), and its built-in widget is not found. The views and actions over it are listed as usual - that is how a person's chat reads and writes it. The developer toolset is unchanged.

describe_app adds views.<name> - { tool, table, allow, params, columns, computed, filter, sort, limit, access }, access being the allow rule's decision for the caller - and one text line per view, view <name>(<params>) over <table>: <explanation>. Columns the caller can never see (a column read rule of nobody, or another role) are left out of tables.<t>.columns; the rules themselves are shown as they are.

Widgets

A table with a widget shows its results as an interactive view in the chat (the MCP Apps extension; ChatGPT reads the same metadata). The built-ins are table (a list with add, edit and delete), form and record. Each result also carries a 15-minute read-only live token for the same caller, so the widget subscribes to the table under that person's read rule and rows changed anywhere - another chat, your web app, the console - appear while they watch.

A custom widget is one HTML document of at most 256 KB, stored per environment with widget_put, the console, or PUT /v1/project/widgets/:name, and served as ui://app/<name>. Including <script src="https://dabadata.com/mcp-widget.js?v=5bce207b"></script> gives it the host bridge and the live helper:

<!doctype html>
<main id="total">...</main>
<script src="https://dabadata.com/mcp-widget.js?v=5bce207b"></script>
<script>
  const w = window.DabadataWidget;
  const show = (rows) => {
    const sum = rows.reduce((s, r) => s + r.amount, 0);
    document.getElementById("total").textContent = `Total: ${sum.toFixed(2)}`;
  };
  w.on("result", (result) => {
    show(w.rowsOf(result));
    w.live(w.liveMeta(result), { onRows: show });   // stays current while the chat is open
  });
</script>

Writes from a widget go through w.callTool("<t>_create", { values }), so they are the signed-in person's and the rules decide.

Connect a client

The one-line setup for Claude Code and Cursor, and how people add the app to ChatGPT and Claude as a connector, are on Build with an AI agent.

The local server (stdio)

For a self-hosted server: an MCP server that runs on your machine and talks to dabadata over HTTP with the project key. The hosted server above needs none of this.

How it acts

The agent is an ordinary end user. When the MCP server starts, it uses the project key to mint a user token for the identity you configure, and every row it reads or writes goes through that token. So the agent is held to the same rules as any person using your app, and its calls show up in the trace under its own id (with source http for now).

The tools that look at the project as a whole - get_schema, read_trace, simulate, reload_schema and mint_user_token - use the project key.

Tools

Install

cd mcp && bun install

The dabadata server must be running; the MCP server talks to it over HTTP.

Add it to Claude Code

Use the absolute path of your checkout in place of /path/to/dabadata:

claude mcp add dabadata -- bun /path/to/dabadata/mcp/src/index.ts

With a different identity or server:

claude mcp add dabadata \
  -e DABADATA_URL=http://localhost:4600 \
  -e 'DABADATA_MCP_USER={"id":"bot","name":"Helper bot","role":"editor"}' \
  -- bun /path/to/dabadata/mcp/src/index.ts

Add it to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (on macOS):

{
  "mcpServers": {
    "dabadata": {
      "command": "bun",
      "args": ["/path/to/dabadata/mcp/src/index.ts"],
      "env": {
        "DABADATA_URL": "http://localhost:4600",
        "DABADATA_MCP_USER": "{\"id\":\"mcp\",\"name\":\"MCP agent\",\"role\":\"admin\"}"
      }
    }
  }
}

Claude Desktop may not have Bun on its PATH. If the server does not start, use the full path that which bun prints as command.

Environment and identity

Pick the identity on purpose. An agent with the viewer role can look but not touch; an editor can create and change its own rows; admin can do what admins can. Whatever it does is in the trace under that id.

Diagnostics go to stderr; stdout is the MCP protocol.

An example conversation

You: What tables are there, and can a viewer delete tasks?

Claude (calls get_schema): There are tasks and announcements. Anyone signed in can read tasks; admins and editors can create them; an admin or the task's owner can update; only admins can delete. So no, a viewer cannot delete tasks.

You: Carol says she couldn't delete something. What happened?

Claude (calls read_trace { user: "carol" }): #39 14:02:11 http delete tasks 5f1c... carol(viewer) denied 3ms - delete tasks: denied, role "viewer" not in ["admin"]. Carol is a viewer and only admins may delete tasks. Give her the admin role, or change the delete rule in projects/default.ts and call reload_schema.