AI assistants & MCP

Tessule has two AI surfaces. Inside the app, three assistants help you design your schema, draft queries and charts, and build dashboards — in conversation. Outside the app, a built-in MCP server lets you connect Claude, VS Code, or any MCP-compatible AI client directly to your workspace’s data and tools.

If you only remember one thing: schema and dashboard AI proposes; a person applies. In-app assistants and MCP authoring tools use the same validated plan endpoints and permission checks as manual changes. MCP record tools act directly with your own workspace permissions; destructive tools require confirmation.

Who can do what

Talking to an assistant needs no special permission beyond seeing the page it lives on. The gated steps are the actions that come out of a conversation:

Step	Action required	Held by default
Chat with the schema assistant	`builder:access` (it lives on the builder’s Data Overview page)	Admins (grantable via custom roles)
Apply a schema plan	`schema:apply`	Admins only
Chat with the query assistant	`builder:access` (SQL console / chart builder pages)	Admins (grantable via custom roles)
Run a proposed query	`query:execute`	Everyone (readers included)
Save a proposed query / chart	`savedQueries:manage` / `charts:manage`	Admins and members
Chat with the dashboard assistant	none beyond seeing the Dashboards page	Everyone
Apply a dashboard plan	`dashboards:manage`	Admins and members
Enable AI record writes over MCP	organization owner/admin (org settings)	Org owners/admins

The buttons hide themselves when you lack the action, but the server is the authority — see Authorization & Permissions.

The propose → validate → apply loop

All three assistants — and MCP schema/dashboard authoring — follow the same loop:

The loop every AI-authored schema or dashboard plan goes through. The dry-run validator and the apply endpoint are the same ones a human author uses; apply revalidates against the current workspace, so a stale plan fails cleanly instead of half-applying.

The validator returns issues — each with a severity (error or warning), a stable machine-readable code (e.g. REF_LABEL_NOT_UNIQUE, NAME_SANITIZED), the exact path of the offending element in the plan, and a fix suggestion. Errors block a plan from being proposed at all; warnings ride along with the proposal so you can judge them. The assistants use these issues to fix their own drafts before you ever see them — the plan card in the chat only appears once validation passed.

The schema assistant

Where: the Data Overview page (the builder’s schema area). It is also the centrepiece of an empty workspace — describe your business and get a working schema.

What it does: interviews you about your operation (structured question forms, not just prose), drafts a schema plan, validates it against your current schema, and shows a proposal card: a markdown summary, the number of new tables and fields, a Preview schema diagram of the proposed structure against what exists, and — for those allowed — an Apply this schema button.

A plan can create tables (with fields, picklist vocabularies, references, formulas), add fields and uniqueness (plain or conditional), no-overlap and check constraints to existing tables, set up derivation rules and views, and designate lifecycle stages. What it can never do is delete, rename, or retype anything — plans are strictly additive, and destructive changes stay in the app UI where their consequences are shown.

Points worth knowing:

Applying uses POST /schema-plans/apply — the same admin-gated (schema:apply), audited endpoint as any other bulk schema change. The whole plan applies in one transaction: everything is created, or nothing is. Members can design freely and preview; the card tells them to ask an admin to apply.
Proposals go stale gracefully. If you keep chatting after a proposal, the card turns amber (“proposed before your latest message”) but stays usable — and because apply revalidates against the current schema, applying a stale plan is safe: it either still fits, or it fails cleanly with issues.
Conversations are saved per workspace and per user, so an interrupted design session resumes where you left off. New chat starts over.
The assistant sees your schema (tables, fields, relationships, descriptions), not your record data.

The equivalent dry-run endpoint, POST /schema-plans/validate, is open to all roles — validation changes nothing and is how the assistant (and MCP clients) check their work.

For schema-as-code workflows, MCP’s export_schema_plan tool returns the current workspace as the same deterministic plan format. You can commit or diff the result, copy it into an empty workspace, or apply it in reconcile mode: matching objects are skipped, missing pieces are created, and differing objects are rejected. Reconcile remains additive — it never renames, retypes, or deletes objects.

The dashboard assistant

Where: the Dashboards page.

What it does: designs analytics as one dashboard plan — new saved queries, charts backed by them, and dashboards arranging the tiles. It is deliberately reuse-first: it lists your existing queries and charts and prefers referencing them over creating near-duplicates (the validator even flags a new query that duplicates an existing one).

Validation (POST /dashboard-plans/validate) checks structure and references, and plans every new SQL query read-only against your workspace — without executing it. Apply (POST /dashboard-plans/apply, requires dashboards:manage) creates everything in one transaction. The result is ordinary saved queries, charts, and dashboards, indistinguishable from ones built by hand — edit or delete them as usual. Plans never modify or delete existing objects.

The query assistant

Where: the SQL console and the chart builder.

What it does: turns “how many deals closed last month, by owner?” into a validated SQL query — and, when you asked for a visualisation, a chart definition to go with it. Its propose_query step parses the SQL and plans it read-only against your real schema, so it never presents a query it hasn’t validated.

The assistant itself never executes the query and never sees any record data. The proposal card puts you in control:

Run — executes it via the ordinary query endpoint (your query:execute action, your daily query quota) and shows the results, with a live chart preview when one was proposed.
Save / Save chart — stores it as a normal saved query or chart (requires savedQueries:manage / charts:manage).
Open in editor — loads the SQL into the console for hand-tuning.

Availability: when an assistant is missing

Each assistant has a status endpoint the app checks before showing the panel: GET /schema-assistant/status, GET /dashboard-assistant/status, and GET /query-assistant/status. Each returns a single enabled flag.

An assistant is unavailable when:

AI features aren’t enabled for your organization (enabled: false) — the panels hide entirely. They are an add-on, not something a workspace admin can switch on locally.
Your organization’s monthly AI budget is exhausted. AI usage is metered in tokens against a per-organization monthly budget (default five million; adjustable per plan). When it runs out, assistant turns are refused with a clear message until the calendar month resets. Metering itself never blocks — only the budget ceiling does.
A single conversation grows too large — the assistant asks you to start a new chat rather than silently truncating history.
The live connection is down — assistant turns stream over the app’s realtime connection; the Send button waits for it to reconnect.

MCP: connect external AI clients

The MCP server lets Claude, VS Code, or any MCP-compatible client work with your workspace directly. It is a thin adapter over the regular REST API: every tool call is forwarded to the corresponding API endpoint with the caller’s own credentials, so authentication, authorization, validation, and audit logging happen exactly once, identically for AI clients and the web app. There is no AI side door.

Connecting

Open Workspace Settings → AI & MCP and copy the MCP server URL. Each workspace has its own URL — the connection (and the OAuth grant behind it) is locked to that one workspace, so you can keep connections to several workspaces side by side.
In Claude: Settings → Connectors → Add custom connector, paste the URL. In VS Code or another client: add it as a remote MCP server.
The client walks you through sign-in and the consent screen — which application, which scopes, which workspace. See API access & tokens for the full OAuth flow, scope meanings, and token lifetimes.

The tools

Group	Tools	Needs
Read structure & data	`describe_workspace`, `list_tables`, `get_table_schema`, `sample_data`, `search_records`	`mcp:read` scope + your own read permissions
Query	`query_data` (read-only SQL, capped at 10,000 rows; a lookup, rollup or computed column is not a SQL column — the refusal carries the equivalent expression, and `get_table_schema` lists it as `sqlEquivalent`)	`mcp:query` scope + `query:execute`
Schema authoring	`get_schema_authoring_guide`, `export_schema_plan`, `validate_schema_plan`, `apply_schema_plan`	guide/export/validate: read access; apply: `mcp:write` scope and `schema:apply` (admin)
Dashboard authoring	`list_saved_queries`, `list_charts`, `list_dashboards`, `get_dashboard_authoring_guide`, `validate_dashboard_plan`, `apply_dashboard_plan`	see note below
Record writes	`create_record`, `update_record`, `delete_record`	`mcp:write` scope + your record permissions + the org opt-in below
Report a problem	`report_issue`, `list_my_issues`, `get_issue`, `reply_on_issue`	Nothing beyond a connection — see below

Two prompts ship alongside the tools for clients that support them: design_crm_schema and design_dashboard — interview-style kickoffs that package the authoring guides.

Telling us when something is wrong

If your assistant hits a bug, a missing capability, or an error it cannot work around, it can file that as an issue without leaving the conversation — report_issue puts it in the same log the in-app feedback widget feeds, with a title, the full description, whatever structured detail it has (the tool it called, the arguments, the error), and up to three small attachments such as a log or a screenshot.

These tools need no scope beyond a working connection and no organization opt-in: reporting a problem with the product is not access to your data, and an assistant that cannot say “this is broken” is one whose knowledge of the problem dies with the conversation. They are self-scoped, so an assistant only ever sees issues you reported.

What we record about the assistant. The agent names itself in the call (“Claude Code”, say), and we store that as what it claims. Separately, we record which registered OAuth client the connection actually belongs to, which is something we observe rather than take on trust. Our operators see both.

Issues are a conversation now. A report is no longer a one-way drop with a status field. We can reply on it, and you (or your assistant) can reply back: answer a question, add a fuller stack trace, narrow a reproduction. Replies show up in the feedback panel in the app, with an unread marker, and through get_issue / list_my_issues.

A reply from us is labelled with who wrote it. A message from a person is shown as one; an automated reply — an acknowledgement, or a pointer at documentation that already answers the question — is labelled as automated, so you always know whether a human has looked at your issue yet. Today nothing replies automatically; the labelling exists so that when something does, it says so.

Record writes are an organization opt-in

The create_record / update_record / delete_record tools are off by default for every organization. An org owner or admin enables “AI record writes via MCP” under Organization Settings (the features toggle, backed by PUT /organizations/{organizationId}/features). Until then the tools are simply absent from the client’s tool list.

The flag only controls whether the tools are offered. Even with it on, every write passes the exact checks the web app’s writes do: the records:create / records:update / records:delete actions from your DB-backed permissions, row-level scopes and field-level restrictions, and full schema validation. A reader’s write is denied with the flag on; the flag never grants anything.

Permissions, honestly stated

The connected user’s own permissions apply, end to end. MCP calls run as you, in the one workspace you approved. Records and fields you can’t see can’t be read, matched, or leaked into search snippets.
Scopes cap, roles grant. The token’s scopes are intersected with your role-based permissions — see API access & tokens.
Non-admins never see apply_schema_plan in the tool list, and the endpoint enforces the admin gate regardless of what a client cached.
Role changes propagate at token refresh (30-minute access tokens; refresh re-verifies membership and role), so revoked members and demotions take effect within half an hour at most.

Audit and events

Everything an MCP client does lands in the same records as everything else:

Mutations appear in the workspace audit trail, attributed to the connected user.
Writes emit the standard application events, tagged with source: "mcp" and the tool name — so the UI live-updates, and you can tell an AI-made change from a hand-made one.

Safety notes

Same validator for AI and humans. AI-authored plans go through the identical validation and apply pipeline as manual ones; there is no relaxed “AI mode”.
Schema plans are additive-only. No AI path can delete, rename, or retype a table or field. Destructive schema changes exist only in the app UI, in front of a person.
Applies are atomic and revalidated. A plan validated against yesterday’s workspace is re-checked at apply time and fails cleanly rather than half-applying.
delete_record is the one irreversible AI action — and it requires the org opt-in, the mcp:write scope, your own records:delete permission, and (per the tool’s own instructions) explicit user confirmation in the AI conversation. Deleting a record can also remove rows derived from it, and the consent screen says so.
Cost is bounded. All in-app assistant usage is metered against the organization’s monthly AI token budget.

FAQ

Q: I don’t see any AI panels at all.

AI features aren’t enabled for your organization (the status endpoints return enabled: false) — this isn’t something a workspace setting controls. If others in your workspace see the schema or query assistant and you don’t, you’re likely missing builder:access (those two live on builder pages).

Q: The assistant proposed a plan but I can’t apply it.

Applying a schema plan needs schema:apply — admins only. The card shows “Ask a workspace owner or admin to apply this schema” in that case; they can open the same conversation outcome and apply it. Dashboard plans need dashboards:manage (members have it).

Q: Does the AI see my records?

The schema assistant sees your schema, not your data. The query assistant validates SQL without executing it and never sees results — you run the query. The dashboard assistant sees query/chart/dashboard definitions. Over MCP it’s different by design: query_data, sample_data, and search_records return real data (that you can see) to the AI client you connected — that’s their purpose.

Q: Can an MCP client change my schema behind my back?

It can propose freely (validate_schema_plan changes nothing). Executing requires an admin’s grant on the token (mcp:write scope and the admin role), and the tool’s contract instructs the AI to show you the validation summary and get confirmation first. Every apply is audited with source: "mcp".

Q: The assistant said my organization reached its AI limit.

The monthly AI token budget is spent. It resets at the start of the next calendar month; your org owner can ask about a higher budget. MCP usage with external clients (e.g. Claude) spends that client’s tokens, not this budget.

Open the app