Making Changes
Preview and apply changes to dashboards and semantic models through Semaphor MCP.
Agents can add, change and remove dashboard cards and report filters, change how cards read and show, arrange a dashboard's layout, add and rename sheets, show cards as tabs, write text cards, build a whole new dashboard in one proposal, improve a semantic model's labels, descriptions, synonyms, example questions and instructions, and add a relationship to it. Every change goes through two tools: semaphor_propose_change previews it and saves nothing, and semaphor_apply_change saves it: a dashboard change exactly as previewed, a semantic model change only if nothing it replaces has changed since, and each relationship after checking it against the domain as it is then.
To change the dashboard a user is looking at in your product instead, unsaved and with Undo, use a live token: see Live Changes in Embedded Dashboards.
Quick Start
Read the dashboard
The agent calls semaphor_get_dashboard_details with fields: ["outline"]. The outline lists every sheet, card and filter by ID and name, each card's query in the same fields semaphor_analyze uses, the layout of each sheet, which cards and filters can be changed, and whether you can edit the dashboard or need to save a copy. See The outline.
{ "dashboardId": "d_8f2k", "fields": ["outline"] }Propose
The agent calls semaphor_propose_change with the dashboard and a list of changes. It gets back a proposalId, one plain sentence per change, any warnings, and the new numbers for the cards it changed. Nothing is saved.
{
"dashboardId": "d_8f2k",
"changes": [{
"op": "card.add",
"type": "bar",
"title": "Revenue by region",
"query": {
"domainId": "dom_sales",
"datasetName": "orders",
"measures": ["revenue"],
"dimensions": ["region"],
"dateField": "order_date",
"timeWindow": { "kind": "periods", "unit": "day", "from": -29, "to": 0, "anchor": "now" }
}
}],
"rationale": "Regional managers asked for a 30-day view."
}Review
The agent shows you the sentences and the preview, and waits for you to confirm. Your client may also ask before the apply runs: see Permission and Approval.
Apply
The agent calls semaphor_apply_change with the proposalId, and the changes are saved exactly as previewed.
{ "proposalId": "chg_..." }Who Can Make Changes
semaphor_propose_change appears for every session whose user can author dashboards: an organization user with an Author role or higher, or an end user with the Power User role. Proposing saves nothing, so a read-only session can propose. semaphor_apply_change is listed only for sessions with the mcp:write scope. Which dashboards you can change is decided the same way as in the app: you can edit the dashboards you own or were given edit access to, and save a private copy of any dashboard you can open, if you can create dashboards in its project.
| Change | Logged in (OAuth) | Automation token | End-user token (Power User) |
|---|---|---|---|
| Dashboard cards, filters, sheets, tabs, text cards, layout and calculated fields | Yes | Yes | Yes, on dashboards they can edit in their own tenant |
A new dashboard (create) | Yes | Yes | Yes, in their own tenant |
A semantic model's labels, descriptions, Context, formats and definitions (domain.update, dataset.update, field.update, metric.update, calculation.add, calculation.update, relationship.update) | Yes | Yes | No |
relationship.add | Yes | Yes | No |
Semantic model changes affect every query on a domain, so who may make one follows your role, the same rule as the semantic domain editor: an organization user with the Author role or higher, in the project's organization, with access to the domain, logged in or with a token. End users never change semantic models, and end users with the Viewer role never get change tools. The SQL query form appears only for sessions that can use SQL.
To apply changes, a session needs write scope: log in with a client that requests mcp:read mcp:write, or mint a token with "mcp": { "scopes": ["mcp:read", "mcp:write"] }. See Authentication and Security and Connect with a Token.
Proposals
semaphor_propose_change takes one target and a list of changes:
| Argument | Required | Description |
|---|---|---|
dashboardId | For changes to a dashboard | The dashboard to change |
create | For a new dashboard | { "title", "description" } in place of dashboardId: the changes build a new private dashboard. See Build a New Dashboard. |
domainId | For semantic model changes | The semantic domain to change. With dashboard changes it is ignored: each card query and filter names its own domain. |
changes | Yes | 1 to 20 changes for a dashboard, up to 50 for a new one, applied in order, all or nothing; 1 to 20 of a domain's own changes; or 1 to 5 relationship.add for one domain. One proposal holds one kind: dashboard changes, a domain's own changes, or relationships. |
saveAs | No | "original" (default) or "copy": save the changes as your own private copy |
preview | No | "sample" (default, up to 5 rows per changed card), "rows" (up to 50) or "none" |
include | No | ["outline"] also returns the dashboard's outline as it will be after the changes, as proposedOutline |
rationale | No | Why the change is needed, in up to 500 characters. It's kept with the proposal. |
projectId | No | Interactive sessions pass the project for create and semantic model changes; dashboard changes use the dashboard's own project |
It returns:
{
"proposalId": "chg_...",
"expiresAt": "2026-10-16T15:12:00Z",
"risk": "low",
"target": { "kind": "dashboard", "dashboardId": "d_8f2k", "title": "Sales", "saveAs": "original" },
"summary": ["Adds the card \"Revenue by region\" (bar) to Overview: revenue by region, last 30 days. The dashboard's \"Region\" filter applies to it."],
"changes": [
{ "index": 0, "op": "card.add", "ref": "$card_1", "title": "Revenue by region",
"sentence": "Adds the card \"Revenue by region\" (bar) to Overview: revenue by region, last 30 days. The dashboard's \"Region\" filter applies to it." }
],
"warnings": [],
"preview": {
"cards": [
{ "ref": "$card_1", "title": "Revenue by region",
"columns": [{ "name": "region", "label": "Region" }, { "name": "revenue", "label": "Revenue" }],
"rows": [["East", 412880], ["West", 288104], ["North", 190455]], "rowCount": 3 }
]
},
"next": "Show the summary to the user. After they confirm, call semaphor_apply_change with proposalId \"chg_...\"."
}| Field | What it holds |
|---|---|
proposalId | The ID to apply. Proposals expire at expiresAt, 30 minutes after proposing. |
risk | low when the changes add, update or arrange; medium when they remove or exclude anything, make a library visual's card local to the dashboard, or add a relationship. A semantic model's labels, descriptions, Context, formats and new calculations are low; a change to a definition (a formula, a default aggregate, a date grain, a primary date, a relationship turned off or rejoined) is medium. |
target | { "kind": "dashboard", "dashboardId", "title", "saveAs" }, { "kind": "new_dashboard", "title" } for create, or { "kind": "domain", "domainId", "name" } for a semantic model change |
summary | One sentence per change, in order. Show these to the user. |
confirm | not_needed when the proposal only changes how cards read and show, the dashboard's title and description, or a sheet's name, so it can be applied at once; needed otherwise, including a new dashboard, a new sheet, tabs, a text card's words and every semantic model change. Left out when the change went to your watch page, where nothing is applied. See Confirm. |
changes | The same sentences with each change's index, op, ref (its handle or ID) and title, and the ruleId a highlight.add creates |
warnings | Things the proposal does that the user should know about. See Warnings. |
preview.cards | Up to 5 changed cards run with their new query: columns, rows, rowCount, and truncated: true when there were more rows than the preview shows |
preview.skipped | Changed cards beyond the first 5, not run |
preview.failed | Cards that didn't run: { ref, title, code, message }. The proposal still stands, so fix the query or apply anyway. |
proposedOutline | With include: ["outline"]: the outline as it will be after the changes |
next | What to do now, in a sentence. A session without mcp:write is told to have the user make the change in the dashboard editor (on the domain page for a semantic model change), or ask again from a connection that can apply. |
- Only you can apply your proposal, in the same organization and project, with access to the project at the time you apply. Anyone else gets
proposal_not_found. - Handles name new cards, filters and sheets. Give a
card.add,filter.addorsheet.addahandlesuch as"$region"and use it in later changes of the same list wherever a card, filter or sheet ID goes, except incard.removeandfilter.remove. A sheet's handle goes incard.add'ssheetId, a filter'ssheetIdsandlayout.arrange. Acard.addwithout one gets$card_1,$card_2and so on.
Change a Dashboard
Take cardId, filterId and sheetId values from the outline. On a dashboard with one grid sheet, card.add and layout.arrange use it when you leave out sheetId.
| Change | Fields |
|---|---|
card.add | type, title, and query, or text for a text card; optional handle, sheetId, description, matrix, width, position, and the card settings below |
card.update | cardId; send only what changes, from type, title, description, query, matrix, text (text cards) and the card settings: columns, orientation, stack, donut, totals, dataLabels, legend, axes (see How Cards Read and Show) |
card.remove | cardId |
filter.add | label, domainId, datasetName, field; optional handle, selection, showAs, defaultValues, defaultCondition, defaultPeriod, sheetIds, or cardId and position to pin it on a card |
filter.update | filterId; optional label, selection, showAs, defaultValues, defaultCondition, defaultPeriod, sheetIds (null clears defaultValues, defaultCondition on a range, defaultPeriod and sheetIds), position and cardId for a pinned filter |
filter.remove | filterId |
filter.bind | filterId, cardId, field: the field of that card's dataset the filter applies through |
filter.exclude | filterId, cardId: stops the filter applying to that card |
layout.arrange | optional sheetId, keepOrder |
layout.tabs | cardIds: two or more cards on one sheet, the first shown |
layout.untab | cardId: a card in tabs, given its own spot |
sheet.add | title; optional handle |
sheet.update | sheetId, title |
highlight.add | cardId, column, and when with color, or scale, or bars; optional apply |
highlight.remove | cardId, ruleId |
dashboard.update | optional title, description (null removes it) |
Number filters
A filter on a number field shows as "range" (viewers pick a condition) or "list" (viewers tick values), set with showAs. A new number filter is a range unless showAs says "list" or the change gives defaultValues to tick. A range's default is defaultCondition, in the card filters' vocabulary, { "operator", "values" }:
| Operator | values |
|---|---|
between, not_between | two numbers, low then high |
>=, <=, >, <, =, != | one number |
is_null, is_not_null | none |
{ "op": "filter.add", "label": "Order amount", "domainId": "dom_sales", "datasetName": "orders", "field": "amount", "defaultCondition": { "operator": ">=", "values": [500] } }The outline reads both back: showAs on every number filter, and on a range defaultCondition, or defaultValues when it was saved earlier with values to tick. Switching showAs drops the default the other kind held; the change's sentence says so.
Refused, with the fix:
showAsother than"range"or"list", or on a field that isn't a number;defaultConditionon a list or a date filter,nullincluded (clear a list's default withdefaultValues: null);defaultValueson a range;- another operator, the wrong count of numbers, values that aren't numbers (
["500"]), a first number above the second, or a key other thanoperatorandvalues.
Cards
type is one of kpi, bar, line, area, pie, table, detail_table, matrix or text. A text card takes text and no query: see Text cards. A Matrix also takes matrix: { "columns": [...] }: the query fields that run across the top; the rest run down the side.
A card's query comes in one of three forms:
| Form | Fields |
|---|---|
Metric query (every type but detail_table) | domainId, datasetName, measures (at least one); optional dimensions, dateField, timeGrain, filters, timeWindow, orderBy, limit |
Records query (detail_table) | domainId, datasetName, columns (at least one); optional filters, dateField, timeWindow, orderBy, limit |
| SQL query (sessions that can use SQL) | connectionId, sql |
- Fields are names from
semaphor_get_dataset_schema, or{ "name", "datasetName" }for a field of a related dataset. - Measures may add an
aggregate:SUM,COUNT,AVG,MIN,MAX,MEDIANorDISTINCT."__count"counts rows. timeGrainisminute,hour,day,week,month,quarteroryear.timeWindowtakes thesemaphor_analyzewindows a saved card can hold, which are the ones the editor saves. Days and longer count whole periods: the last 30 days, today included, is{ "kind": "periods", "unit": "day", "from": -29, "to": 0, "anchor": "now" }. Arollingwindow in days or longer is refused, and itsfixoffers the two whole-period readings: ask your user which they mean. Minutes and hours, such as{ "kind": "rolling", "unit": "minute", "n": 45, "anchor": "now" }, need a date field with a time of day.filtersare{ "field", "operator", "values" }withoperatorone of=,!=,in,not_in,contains,not_contains,between,not_between,>,>=,<,<=,is_nulloris_not_null. Add"scope": "aggregate"to filter a measure after it's aggregated.orderByis{ "field", "direction": "asc" | "desc" }.limitis up to 1,000 rows.
Card filters saved in the editor read in the same vocabulary: one that matches text starting with "V" reads as contains with the value V%, which runs the same match.
card.update's query is a patch: keys you send replace those keys, keys you leave out stay, null clears an optional key, and arrays replace whole. A change from one query form to another needs the complete query of the new form; otherwise it's refused with query_form_mismatch.
{
"dashboardId": "d_8f2k",
"changes": [
{ "op": "card.update", "cardId": "c_trend", "type": "line", "title": "Weekly revenue", "query": { "timeGrain": "week" } }
]
}A type change works the way the type picker does in the editor: settings the new type can use stay, the others go, and the warning type_change_drops says what went. When you change a field's aggregate or time grain, the column keeps its label and format, and a custom label that may no longer fit is reported with label_kept_after_change.
A change touches only what it names. A new row limit leaves the card's measures, groupings and filters exactly as they were, adding a measure keeps every existing column as it is, and a new time grain changes the date where it sits, so a chart grouped by segment and then month stays that way. This holds for cards built in the editor too. Renaming a column alone, such as { "dateField": { "name": "order_date", "label": "Order day" } }, renames it in place and changes nothing else, and the editor keeps the new name. A row limit you set comes with a sort, so a limited card shows its top rows, not arbitrary ones; otherwise a card without a sort keeps none, as in the editor. Clearing the limit ("limit": null) leaves the 100 rows a new card shows.
The sentence for an added card says which dashboard filters reach it. A card that shows a library visual becomes local to the dashboard when you change it, as Apply Local does in the editor; the proposal says so with detaches_linked_visual.
Where a card goes
Without width or position, a new card is placed by its kind: a KPI joins the KPI row on top, a chart pairs with a lone chart in the last row, and a table or text card goes to the end at full width. Give a place only when the user names one:
| Field | Values |
|---|---|
width | full, half, third or quarter. With no position, the card goes after the last card, beside it when the row has room, so two halves sit side by side. |
position | "top", "end", or { "after": "<cardId or handle>" }: right after that card, on that card's sheet |
{
"dashboardId": "d_8f2k",
"changes": [{
"op": "card.add", "type": "kpi", "title": "Revenue, last 30 days",
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"],
"dateField": "order_date", "timeWindow": { "kind": "periods", "unit": "day", "from": -29, "to": 0, "anchor": "now" } },
"position": "top", "width": "full"
}]
}Layout is always stated in these words, never as coordinates. Every other screen size follows the desktop layout.
Arrange a sheet
layout.arrange lays a grid sheet out on every screen size: an introductory text card on top, then KPIs in a row, charts in pairs, tables full width and any other text. "keepOrder": true keeps the cards in their current order and only fixes sizes and gaps. Arranging an empty sheet changes nothing and says so.
{ "dashboardId": "d_8f2k", "changes": [{ "op": "layout.arrange" }] }Sheets
sheet.add adds a grid sheet at the end, and sheet.update renames one. Give a new sheet a handle to put cards and filters on it in the same proposal:
{
"dashboardId": "d_8f2k",
"changes": [
{ "op": "sheet.add", "handle": "$regions", "title": "Regions" },
{ "op": "card.add", "sheetId": "$regions", "type": "bar", "title": "Revenue by region",
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"], "dimensions": ["region"] } }
]
}The sentences read Adds the sheet "Regions". and Renames the sheet "Report" to "Monthly report". Renaming a sheet applies at once; a new sheet asks the user first.
Cards as tabs
layout.tabs puts two or more cards of one sheet in one spot as tabs, the first named shown. layout.untab gives a card its own spot again, beside the tabs it left, at the tabs' size. Cards keep their IDs, settings, filter bindings and highlights; nothing is removed and added again.
{ "dashboardId": "d_8f2k", "changes": [{ "op": "layout.tabs", "cardIds": ["c_monthly", "c_stage"] }] }The outline's layout lists a spot's cards with the shown one first, so reading a spot and sending its cardIds back changes nothing. A text card put in a spot with a KPI shows as the KPI's info, not as a tab, and the proposal says so with tabs_show_as_kpi_info.
Text cards
A text card's text is a list of blocks, shaped like the text editor's own content:
| Block | Fields |
|---|---|
| Heading | { "type": "heading", "level": 1, "content": [...] }, level 1 or 2 |
| Paragraph | { "type": "paragraph", "content": [...] }; "content": [] is an empty line for spacing |
| List | { "type": "list", "style": "bulleted", "items": [[...], [...]] }, style bulleted or numbered, one level |
content and each list item are runs. A run is a string, or an object with text or variable and any of bold, italic and link:
{
"dashboardId": "d_8f2k",
"changes": [{
"op": "card.add", "type": "text", "title": "About",
"text": [
{ "type": "heading", "level": 1, "content": ["Q3 review"] },
{ "type": "paragraph", "content": ["Revenue rose ", { "text": "12%", "bold": true },
". See ", { "text": "the method", "link": "https://example.com/method" }, "."] },
{ "type": "list", "style": "bulleted", "items": [["Inbound up"], ["Outbound flat"]] }
]
}]
}- Text is taken as written.
**,#,_or[x](y)in a run are those characters, so formatting comes only frombold,italicandlink. A new line is a new block. - Links follow the text editor's rule: web, mail and phone links, and links within the app. An address can hold variables:
"link": ["https://crm.example.com/accounts/", { "variable": "customer.value" }]. - Variables. A run names any variable the card's tab offers, by name or
name.part:{ "variable": "facility.label" }, a variable from data, or a report value. See Variables and Document text. - What a change keeps. The outline reads a text card in the same blocks. Send them back with your change, and every block you leave as it reads keeps everything stored with it, such as a variable's date format. What the blocks can't state, such as underline from the older text editor, is listed in the card's
editorOnlyand kept. - A text card's words change with
card.update'stext; itstitleanddescription(shown under the title) change as any card's.
Variables and Document text
Text names values through variables: an input's value, a report value such as generatedAt, or a variable from data. The outline's variables lists each one with its kind, its question in words, its parts, where text uses it (usedIn) and whether you can change it.
A variable from data is a named question with one answer, derived where it shows under that tab's or Document's filters. Add one with variable.add, giving the query a card takes and how its value is taken (get):
{
"op": "variable.add", "name": "net_purchases", "get": "aggregate",
"query": { "domainId": "dom_sales", "datasetName": "purchase_lines",
"measures": [{ "name": "net_purchase_value", "aggregate": "SUM", "comparison": { "kind": "shift", "unit": "period" } }] }
}get | Query | Shows |
|---|---|---|
only | one dimension | The value when exactly one row matches; nothing when more do |
first | one dimension and orderBy | The first value by that order |
list, or { "kind": "list", "limit", "separator" } | one dimension | The distinct values, joined |
aggregate | one measure with its aggregate | One value, which may take a comparison: a step back such as the period before or last year |
variable.update changes a variable by name (rename renames it; text keeps showing it), and variable.remove is refused while text uses it, naming where. filter.bind and filter.exclude take a variable's name where they take a card.
A variable's comparison is always a step it names, such as { "kind": "shift", "unit": "period" } or { "kind": "shift", "unit": "year" }. It never follows the Date filter, so { "kind": "inherit" } is refused, as is a target. A comparison adds the parts previous, change and percentChange (a ratio). A run shows a part and says how it reads in presentation: decimals, a date format, units, signWords, absolute, percent, and colors in the highlight words:
{ "variable": "net_purchases.percentChange",
"presentation": { "percent": true, "absolute": true, "signWords": ["up", "down", "flat"],
"colors": [{ "when": { "operator": "<", "value": 0 }, "color": "red" }] } }Words that follow a value are a block run, never a template:
{ "when": { "variable": "manager.email", "is": "present" }, "then": [{ "variable": "manager.email" }],
"else": ["No contact on file"] }is is present, empty, equals, below or above (the last three with value). An else holding one block is a chain.
document.text.update writes a Document line or text section as runs: target is { "region": "header", "role": "title" } (or metadata, note, pageInfo in a footer) or { "sectionId" }. Document text takes links, variables and blocks as a text card's does.
Text holds words and variables, never formulas: a variable that isn't a name is refused with text_holds_no_formulas. Put the formula in a domain calculated field or a SQL variable, then name the variable. To check what a variable shows, call semaphor_analyze with fromVariable: { dashboardId, name, sheetId }.
Filters
A filter applies to the cards on its sheets that it can reach; the outline's reaches lists them. selection is single or multiple (default). sheetIds defaults to every grid sheet. defaultPeriod is a date filter's default window, in the same form as a card's timeWindow.
{
"dashboardId": "d_8f2k",
"changes": [
{ "op": "filter.add", "handle": "$region", "label": "Region", "domainId": "dom_sales", "datasetName": "orders",
"field": "region", "selection": "single", "defaultValues": ["East"] },
{ "op": "filter.bind", "filterId": "$region", "cardId": "c_orders", "field": "region_code" }
]
}- A new or changed filter that doesn't reach some cards on its sheets comes back with the warning
filter_not_reaching_cards, listing those cards withsuggestedFieldsfrom the domain's relationships. Add afilter.bindwith one of them, or leave the cards unfiltered. - Binding a filter to a card the filter leaves out by name brings the card back in.
- A filter default loads as you ask for it. The outline says which date picker a date filter uses (
datePicker:day,monthorrange). A single-day picker takes a one-day default, such as today or yesterday, and a month picker takes a whole month, such as this month or last month. A default the picker would narrow is refused withfilter_not_editableand afix. - A
defaultPeriodmoves with time and counts from when the dashboard opens, so its anchor is"now"or, for whole periods,{ "lastComplete": unit }. Year to last completed month is{ "kind": "periods", "unit": "year", "from": 0, "to": 0, "toDate": true, "anchor": { "lastComplete": "month" } }. A default anchored to"latest_data", or with fixed dates, is refused with afix. - The outline reads a filter's default back as
defaultPeriod, in the form you'd send. A default saved earlier that can't be saved now, such as a rolling 7 days, also carriesdefaultPeriodReadOnly: the refusal a write of it would get, with the windows that can replace it. It stays as long asfilter.updateleavesdefaultPeriodout. - Anything that wouldn't take effect is refused rather than saved: a filter not shown on the card's sheet, a binding to a field of another type, or a card change that would leave a filter with nothing to filter. The
fixsays what to do. A proposal never reports a change that didn't happen.
Conditions every card shares
A condition every card on a sheet shares, such as the last 90 days or one region, belongs in one dashboard filter's default rather than in each card's filters or timeWindow, so viewers change it in one place. Add a filter with that default (filter.add), or change the default of the filter the outline already has on that field (filter.update), and keep conditions in a card's query only when some cards need them or a default can't hold them: fixed dates, windows counted from the newest data, "is not", "contains" and conditions on a measure's total. When a proposal leaves the same condition on every card a filter on its field would reach, it comes back with repeated_card_condition, naming those cards, any other cards the filter would narrow, and the changes that move it. When a card's own condition repeats the default of a filter that reaches it, card_condition_repeats_filter_default says the card won't follow the filter, with three choices: remove the card's condition so it follows the filter, keep both so it shows only what both allow, or exclude the card from the filter so it always shows its own. Both are warnings: the proposal is still valid as it is.
Pinned filters
A pinned filter sits on one card, above its visual, and narrows only that card. Viewers see the card's pinned filters first, in the order you set. Give filter.add a cardId instead of sheetIds; it takes the same selection, showAs and defaults as a dashboard filter. position places it among the card's pinned filters, 0 first.
{ "op": "filter.add", "cardId": "c_orders", "position": 0, "label": "Region", "domainId": "dom_sales",
"datasetName": "orders", "field": "region", "defaultValues": ["East"] }- The outline lists a card's pinned filters under its
pinnedFilters, in order, each with itsfilterId,fieldand default.filter.updateandfilter.removetake thatfilterId, and the card's id ascardId;filter.updatewithpositionmoves it. - Copies of one visual (a duplicated sheet keeps a linked visual's filters) share pinned filter ids. Send
cardIdto name which card's filter you mean: an id on more than one card without it is refused, naming the cards, and so is acardIdwhose card doesn't have the filter. - A card takes one pinned filter per field. A second one is refused; change the first with
filter.update. - Pinned filters go on charts and tables; a KPI or a text card refuses them.
sheetIdswith acardIdis refused, since a pinned filter shows on its card, and so is a field from another domain than the card's. - A pinned filter's default is checked as a dashboard filter's is: one its picker would narrow is refused with
filter_not_editable.
Calculated fields
A dashboard keeps its own calculated fields beside its domain's: a formula over one dataset's fields that any card on the dashboard can show. A dashboard proposal adds, changes and removes them, and the outline lists them under calculatedFields: each field's formula over named {tokens}, the inputs each token reads (a field, with its aggregate where the formula reads the bare input), and the cards that use it (usedBy). Those are the words calculation.add and calculation.update take back.
| Change | Does |
|---|---|
calculation.add | Adds a field. It names domainId and dataset as a card query does, a name, and an expression in the dataset's field names; label, description, dataType and use (aggregate, the default, or group_or_filter for a row formula) are optional |
calculation.update | Changes the field name names: its label, description or expression (with inputs when it uses {tokens}). Every card that shows it reads the new formula. A measure stays per row or over aggregates, as it was: for the other, add a new field. A name never changes: change the label |
calculation.remove | Removes the field name names. It's refused while a card or filter uses it; take it off them earlier in the same proposal |
The formula is checked as the domain checks a calculation, then on the connection, so a field that saves runs. A card query names the field like any other field of its dataset: a row formula as a measure with an aggregate, a formula over aggregates as a measure without one, and a group_or_filter field in dimensions. When a dashboard field and a domain calculation share a name, the card query means the dashboard's.
{
"dashboardId": "d_abc",
"changes": [
{ "op": "calculation.add", "domainId": "dom_abc", "dataset": "exports", "name": "duration_secs", "label": "Duration (s)", "expression": "duration_ms / 1000" },
{ "op": "card.update", "cardId": "c_avg", "query": { "measures": [{ "name": "duration_secs", "aggregate": "AVG" }] } }
]
}The first change reads back as "Adds the calculated field Duration (s) to this dashboard: duration_ms / 1000, for each row." A formula change says how many cards use the field.
A formula that reads another dataset or a domain metric belongs on the domain: propose calculation.add with the domain's domainId and no dashboardId (see Definitions and new calculations), then name it in the card's query. These stay in the editor, and the outline lists them under editorOnly:
- A dashboard field over more than one dataset, or over a dataset the card joins
- A dashboard field on a Matrix (a Matrix takes domain calculations)
- A date grouping on a dashboard field, or a condition on a dashboard field that is a measure
A dashboard field can sit beside the fields its formula reads (Margin beside Sales and Cost), sort the card, and filter it when it is a row formula. A number format for a dashboard field goes on the card's columns.
What can be changed
The outline marks each card and filter editable. A card that isn't carries notEditable.reason:
| Reason | The card |
|---|---|
text | A text card whose words come from a query |
document_section | A card in a Document section |
custom | A custom visual |
needs_sql_access | A SQL card, for a session that can't use SQL |
type_not_supported | A chart type beyond the eight above and their variants (horizontal and stacked bars, stacked lines and areas, doughnuts, which read as their type with a property) |
not_expressible | Uses something the public query can't state (a database table instead of a dataset, a Python card, a join set up in the editor); detail names it |
These cards can be read and removed, and are changed in the editor. A filter that isn't editable has kind and a reason: global_date (the report's date filter), not_semantic (a filter on a database table) or scope_not_expressible (a filter scoped to chosen cards). Those can be removed or excluded through the MCP.
The Outline
semaphor_get_dashboard_details with fields: ["outline"] returns the dashboard in the change vocabulary. Narrow it with sheetIds or cardIds.
{
"outline": {
"dashboardId": "d_8f2k",
"title": "Sales",
"updatedAt": "2026-10-16T14:02:11.420Z",
"access": { "canEdit": true, "canCopy": true },
"datasets": [{ "domainId": "dom_sales", "datasetName": "orders" }],
"sheets": [
{
"sheetId": "s_overview", "title": "Overview", "kind": "dashboard",
"cards": [
{ "cardId": "c_total", "title": "Revenue", "type": "kpi", "editable": true,
"source": { "kind": "semantic", "domainId": "dom_sales", "datasetName": "orders" },
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"] } },
{ "cardId": "c_trend", "title": "Revenue by day", "type": "line", "editable": true,
"source": { "kind": "semantic", "domainId": "dom_sales", "datasetName": "orders" },
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"],
"dateField": "order_date", "timeGrain": "day" } },
{ "cardId": "c_notes", "title": "Notes", "type": "text", "editable": true,
"text": [{ "type": "paragraph", "content": ["Revenue for ", { "variable": "region.label" }, "."] }] }
],
"layout": [
{ "tiles": [{ "cardIds": ["c_total"], "width": "full" }] },
{ "tiles": [{ "cardIds": ["c_trend"], "width": "half" }, { "cardIds": ["c_notes"], "width": "half" }] }
]
}
],
"filters": [
{ "filterId": "f_region", "label": "Region", "editable": true, "domainId": "dom_sales", "datasetName": "orders",
"field": "region", "selection": "multiple", "sheetIds": "all",
"reaches": ["c_total", "c_trend"], "excluded": [], "notReached": [] }
]
}
}| Field | What it holds |
|---|---|
updatedAt | When the dashboard was last saved. An apply checks it: a newer save means proposal_stale. |
access | canEdit: change it in place. canCopy: you can't edit it but can save a private copy with "saveAs": "copy". |
datasets | Every dataset a card or filter uses |
sheets[].kind | dashboard (a grid sheet, which takes cards) or document (its section cards are listed, never editable) |
sheets[].cards[] | cardId, title, type, source, editable, the query (and matrix) for editable cards, text (and editorOnly) for a text card, linkedVisualId for a card showing a library visual, notEditable otherwise. A query's timeWindow is the card's stored window; one a card can't be saved with now also carries timeWindowReadOnly beside the query, with the refusal and the windows that can replace it, and stays while card.update leaves timeWindow out. |
sheets[].layout | Grid sheets only: the desktop layout as rows from the top. Each tile is one frame with its width (full, half, third, quarter) and its cards, the shown card first (a frame can hold cards as tabs). It always covers the whole sheet, even when cardIds narrows the cards. |
filters[] | Each filter with its field, selection, defaults (a date filter's defaultPeriod, and defaultPeriodReadOnly when it can't be saved again), datePicker, sheetIds ("all", or a list), exceptSheetIds, includesDocumentSheets, and its reach: reaches (card IDs it applies to), excluded, notReached (in scope, not matched) and blocked |
truncated | Present when the dashboard has more than 50 cards: queries are left out. Narrow with sheetIds or cardIds to get them. |
Save, Copy and Apply
Saving a copy. When the outline says "access": { "canEdit": false, "canCopy": true }, propose with "saveAs": "copy". The copy is private to you, keeps the original's card and filter IDs, and is named "title (copy)". The apply response names the copy in target and the original in target.copiedFrom.
semaphor_apply_change returns:
{
"applied": true,
"replayed": false,
"target": { "kind": "dashboard", "dashboardId": "d_8f2k", "title": "Sales", "updatedAt": "2026-10-16T14:20:03.114Z",
"url": "https://semaphor.cloud/project/p_.../dashboard/d_8f2k" },
"created": [{ "handle": "$region", "kind": "filter", "id": "f_91c2", "title": "Region" }],
"summary": ["Adds the filter \"Region\" on every sheet, single select, default East."],
"warnings": []
}| Field | What it holds |
|---|---|
applied | true when the change was saved |
replayed | true when this is the recorded result of an earlier apply of the same proposal |
target | The dashboard (or domain) changed, with its new updatedAt. url opens it in Semaphor, for organization users. A copy adds copiedFrom. |
created | What the apply created, with the IDs to use from now on: cards, filters and sheets (with their handle), and for a copy or a new dashboard, { "kind": "dashboard", "id", "title" } |
summary | The sentences that were applied |
warnings | Anything to tell the user, such as commit_failed |
What apply checks. Apply saves only if the dashboard is still the one previewed: if anyone saved it, or a library visual it shows changed, it returns proposal_stale and saves nothing. Read the outline again and propose again. Apply also checks your access again as it is now, so copy_required, not_permitted or capability_required can come from apply too.
Commits. In projects that require a commit message, an organization user's apply commits with the proposal's sentences followed by "(through the MCP)". End users' changes never commit. If the commit fails after the save, the change stays saved and the response carries the warning commit_failed.
Watch Changes Land in Your Browser
When you're logged in to Semaphor MCP with your own account, you can watch the agent's changes land on a dashboard in your browser, and save them yourself.
Open the watch link. Ask the agent for the dashboard's watch link, and open it in a browser where you're signed in to Semaphor. When the agent builds a new dashboard for you, it can give you the link as soon as the dashboard is created. The dashboard opens with Watching beside its title. You need to be able to edit the dashboard.
Ask for changes. Each change the agent makes to that dashboard appears on the page as it's made, unsaved, with Undo, and the page scrolls to the card that changed. You can edit by hand between the agent's changes.
Keep what you want. Save keeps everything on the page. Undo removes a change, and Close leaves without saving.
While you watch, you save. The agent doesn't save the watched dashboard itself, and tells you the changes are waiting on your page. A private copy ("saveAs": "copy") is the exception: it's a new dashboard, so the agent proposes and applies it as usual.
Stop watching. Open Watching beside the title and choose Stop watching to hand saving back to the agent: from its next change on, it proposes and applies as usual. Anything unsaved stays on the page for you to save or drop. Watch again turns watching back on. Watching also ends 8 hours after you opened the page.
If you close the page. Watching stays on until you press Stop watching, so the agent can't change the dashboard and asks you to reopen the watch link. Reopen it, or press Stop watching there to let the agent save.
One page at a time. If you open the link again in another tab, the newest tab receives the changes, and the older tab says "Not watching here" once you stop watching there.
Without the watch page, the agent proposes and applies its changes as described above.
For agents: in logged-in sessions, semaphor_get_dashboard_details returns watchUrl, the link, and watching, true while the user's watch page is on, and semaphor_apply_change returns watchUrl in its target for a dashboard it saved or created. While watching is true, a proposal is not a preview: semaphor_propose_change puts the change on the page and returns delivery with what became of it, and no confirm, since there is nothing to apply. Follow its next, which names the cards the change added or changed: to correct one, change it with card.update, because another card.add adds a second card. When the page is closed, reads and proposals return screen_unavailable.
Build a New Dashboard
Send create in place of dashboardId, with the changes that fill the new dashboard: the same changes you use to edit one, up to 50. Start with sheet.add for each sheet; with none, the dashboard has one sheet.
A new dashboard is laid out for you: after its changes, each sheet with cards is arranged on every screen size, and the summary says so. Leave out width and position to get this; a card.add that states either, or a layout.arrange in the changes, keeps the layout as placed.
{
"projectId": "p_...",
"create": { "title": "Sales review", "description": "Weekly" },
"changes": [
{ "op": "sheet.add", "handle": "$overview", "title": "Overview" },
{ "op": "sheet.add", "handle": "$detail", "title": "Detail" },
{ "op": "card.add", "sheetId": "$overview", "type": "text", "title": "About",
"text": [{ "type": "heading", "level": 1, "content": ["Sales review"] }, { "type": "paragraph", "content": ["Figures update daily."] }] },
{ "op": "card.add", "handle": "$total", "sheetId": "$overview", "type": "kpi", "title": "Revenue",
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"] } },
{ "op": "card.add", "handle": "$trend", "sheetId": "$overview", "type": "line", "title": "Revenue by week",
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"], "dateField": "order_date", "timeGrain": "week" } },
{ "op": "layout.tabs", "cardIds": ["$trend", "$total"] },
{ "op": "card.add", "sheetId": "$detail", "type": "table", "title": "By region",
"query": { "domainId": "dom_sales", "datasetName": "orders", "measures": ["revenue"], "dimensions": ["region"] } },
{ "op": "filter.add", "label": "Region", "domainId": "dom_sales", "datasetName": "orders", "field": "region", "sheetIds": ["$overview", "$detail"] }
]
}- The preview is real. The proposal's first sentence says the whole (
Creates a private dashboard "Sales review" with 2 sheets, 4 cards, and 1 filter.), then one sentence per change, and the changed cards run with real numbers.include: ["outline"]returns the new dashboard's outline as it will be after apply. - Apply saves it private to you, exactly as previewed, with the IDs the proposal showed. The apply response's
targetis the new dashboard; organization users get itsurl, andcreatedlists the dashboard, its sheets, cards and filters. - Who can. Anyone who can create dashboards in the project: organization users, and end users with the Power User role, whose dashboard is saved in their own tenant.
- Retries are safe. Applying the same proposal again returns the recorded result; it never saves a second dashboard.
- The title and description go in
create, so adashboard.updatein a new dashboard's changes is refused. More than 50 changes are refused withtoo_many_changes: create with the first 50, then change the new dashboard in a second proposal.
Change a Semantic Model
As an agent works with a domain, it learns what the fields mean: that people say "revenue" for amount, that refunds are a separate field, which questions come up. It can write that back, so the next question finds the right field. A domain is shared by everyone in the project, so every semantic model change asks for a yes (confirm: needed). Improve a Semantic Model walks through it with example requests.
Labels, descriptions and Context
Four changes edit a domain's own words and settings. Each names its object; read the current values first with semaphor_get_dataset_schema.
| Change | Names | Changes |
|---|---|---|
domain.update | the domain (domainId) | label, description, context |
dataset.update | dataset | label, description, context |
field.update | dataset, field | label, description, context; on a fact (a measure column) format, unit and comparisonPolarity; on a dimension isDisplayField (the field that names a row); hidden: true hides it from agents and field pickers |
metric.update | metric, and its dataset unless it spans datasets | label, description, context, format, comparisonPolarity |
context is the Context agents read beside the description. Synonyms and example questions change one item at a time, so nothing an author typed is replaced:
context field | Does |
|---|---|
instructions | Replaces the instructions; null clears them |
synonyms | { "add": [...], "remove": [...] }. A synonym already there, in any case, is skipped; removing one that's gone does nothing. |
examples | Example questions, { "add": [...], "remove": [...] }, the same way |
{
"domainId": "dom_abc",
"changes": [{
"op": "field.update",
"dataset": "orders",
"field": "amount",
"description": "Order total after discounts, before tax",
"context": { "synonyms": { "add": ["revenue", "sales"] } }
}]
}Each change reads back in one line: what it changes, from what to what, and what stays.
["Orders · Amount: description \"Order total\" → \"Order total after discounts, before tax\"; synonyms + revenue, sales (keeps 2)."]- A name never changes. It's what cards refer to. A change with a
nameis refused with "Change the label instead." nullclears a description (the domain's own included), format, unit or direction.- Limits are the domain's: instructions up to 2,000 characters, up to 50 synonyms of 100 characters, up to 10 example questions of 300 characters. A change past one is refused with the limit, so remove some first.
- All or nothing. Up to 20 changes in one proposal are saved together, or none are.
- Nothing typed by hand is lost. Apply runs the changes again on the domain as it is then. If anything a change replaces (a label, a description, instructions, a format) was changed since the preview, apply returns
proposal_staleand saves nothing. Itschangedlists each value as{ "what", "now" }in the readback's words, such asOrders · Amount descriptionand"Gross order total": read the domain again and propose again. Synonyms and example questions are added to and removed from the lists as they are at apply. - Unhiding a field, keys, dataset sources and SQL, adding or removing datasets, fact filters, date formats, composed dimensions and the formula of a metric across datasets stay on the domain page.
Definitions and new calculations
A definition decides the numbers, so changing one changes what cards show. Its line says what in the domain reads it, and the proposal is risk: medium:
| Change | Changes |
|---|---|
field.update with expression | A calculated field's formula. A field that reads a column has no formula: add a calculation instead. |
metric.update with expression | A metric's formula, for a metric on one dataset |
field.update with defaultAggregate | The aggregate a fact starts with on a card: SUM, COUNT, AVG, MIN, MAX, MEDIAN or DISTINCT |
field.update with granularity | The grain a date dimension groups by, such as month; null removes it |
dataset.update with primaryDateField | The dataset's default date, a date dimension's name; null removes it |
relationship.update | Names a relationship by its name or id; isActive: false turns it off, defaultJoinType is LEFT or INNER, and description and context change as above |
["Orders · Revenue: formula \"SUM(amount)\" → \"SUM(amount) - SUM(refunds)\"; used by Revenue per customer; every card that uses it reads the new definition."]A formula can move a calculation: a row formula that becomes an aggregate turns a fact into a metric, and the line says so ("now a metric"). Everything else it carries (its label, description and Context) stays.
calculation.add adds a calculation by its formula. The domain decides where it goes: a fact, a dimension or a metric on its dataset, or a metric across datasets.
| Field | Values |
|---|---|
name | The new calculation's name, not used by another field or metric on its dataset |
expression | Its formula |
dataset | For a formula over one dataset's fields |
inputs | For a metric across datasets: each {token} in the formula to { "dataset", "field", "aggregate" } or { "metric", "dataset" } |
use | For a row formula: aggregate (default) adds a fact; group_or_filter adds a dimension |
label, description, dataType | Optional |
{
"domainId": "dom_abc",
"changes": [{ "op": "calculation.add", "dataset": "orders", "name": "net_revenue", "label": "Net revenue", "expression": "SUM(amount) - SUM(refunds)" }]
}It reads back as "Adds Net revenue as a metric on Orders: "SUM(amount) - SUM(refunds)"." Nothing uses a new calculation yet, so adding one is risk: low; like every semantic model change, it still asks for a yes.
calculation.update in a domain proposal changes a domain calculation by its name (with dataset for one on a dataset): its label, description or expression, as field.update and metric.update do. A domain calculation is removed on the domain page.
Add a Relationship
relationship.add adds a relationship between two datasets of a domain, so queries can join them. Propose every relationship a card needs together, up to five in one proposal:
{
"domainId": "dom_abc",
"changes": [{
"op": "relationship.add",
"from": { "dataset": "orders", "fields": ["customer_id"] },
"to": { "dataset": "customers", "fields": ["id"] },
"cardinality": "many_to_one",
"defaultJoinType": "LEFT"
}],
"rationale": "Break revenue down by customer segment."
}| Field | Values |
|---|---|
from | The many side: a dataset name and one or more of its fields |
to | The other side, usually a key of that dataset |
cardinality | many_to_one or one_to_one |
defaultJoinType | LEFT or INNER |
description | Optional |
Each relationship is validated when you propose. If a field doesn't exist, the same relationship appears twice, or the domain isn't one you can open, propose returns invalid_change, naming each refused relationship by its path (changes[1]), and stores nothing; if your role or organization can't change the domain, it returns not_permitted.
Apply checks each relationship again against the domain as it is then, so a domain edited after your preview doesn't make the proposal stale. A relationship apply returns target: { "kind": "domain", "domainId" }, an empty created, and relationships, one entry per relationship in order:
status | Meaning |
|---|---|
added | Saved. All the added relationships are saved together. |
existing | An equivalent relationship was already in the domain, for example added on the domain page since your preview. Nothing to do. |
refused | No longer valid (a dataset or field is gone, or the fields' types don't match); message says why. Propose it again once fixed, or leave it. |
summary says the same in a sentence per relationship ("Added orders to customers."), so you can show it to the user as it is. Apply returns proposal_stale only when someone saves the domain during the apply itself; nothing was added, so propose again.
Retries
semaphor_apply_change is safe to retry with the same proposalId. A change is never applied twice.
| You call apply again and the first apply... | You get |
|---|---|
| Succeeded | The recorded result again, with replayed: true |
| Failed | The recorded error. Propose again if you still want the change. |
| Is still running | apply_in_progress. Retry the same call shortly. |
| Started over 5 minutes ago and never recorded a result | apply_outcome_unknown, with a howToCheck message that says how to check whether the change landed |
If your client loses the response to an apply, retry the same call. You get the same result back, not a second copy or dashboard. Records are kept for 24 hours, so a retry still answers after the proposal itself has expired. After apply_outcome_unknown, follow howToCheck before proposing again.
Errors
Change tools return errors as isError: true results with a code, a message and, for most codes, a fix that says what to do next. Problems with individual changes are listed in problems, each with a path such as changes[2].query.measures[0], and the top-level code is the first problem's. A list with any problem is refused whole, and nothing is stored.
| Code | Meaning | What to do |
|---|---|---|
write_scope_required | The session doesn't have mcp:write; the error lists requiredScope and grantedScopes | Log in with write access, or mint a token with mcp:write |
invalid_change | A change doesn't match the tool's fields, more than 5 relationship.add in one proposal, or the same relationship twice | Fix the fields named in problems |
too_many_changes | More than 20 changes for a dashboard or a semantic model, or 50 for a new dashboard | Split them across proposals |
invalid_change_target | The target doesn't fit the changes | Dashboard changes take dashboardId; a new dashboard takes create, without dashboardId or saveAs; semantic model changes take domainId and no dashboardId, with relationship.add in a proposal of its own |
copy_required | You can view the dashboard but not edit it | Propose again with "saveAs": "copy" |
not_permitted | You can't make this change at all, for example create a dashboard in this project, change this semantic domain, or commit where the project requires it | Ask an admin for access |
project_not_found | The projectId for create or relationship.add isn't one you can reach | Use a project from semaphor_list_projects |
dashboard_not_found | The dashboard doesn't exist, or you can't open it | Find it with semaphor_list_dashboards |
card_not_found, filter_not_found, sheet_not_found | An ID isn't on this dashboard; position.after names a card that isn't on a grid sheet | Read the outline again and use its IDs |
handle_unknown | A handle is used before a change defines it | Define the handle in an earlier change, or use an ID |
sheet_required | The dashboard has several grid sheets and card.add or layout.arrange named none | Pick one of the sheets the error lists |
sheet_not_a_grid | The sheet is a Document, or the dashboard has no grid sheet, so it takes no card and can't be arranged | Use a grid sheet from the outline, or add one with sheet.add earlier in the list |
layout_invalid | layout.tabs names one card, cards on two sheets, a card in a Document section, or a custom visual's input | Name two or more cards of one grid sheet |
text_invalid | A text card's run can't be stored: a line break in text, a link the text editor drops, both or neither of text and variable, or a variable the card doesn't have. The path names the run. | Follow the fix; add a new variable in the editor |
field_not_found | A field isn't in the dataset | Use one of the fields the error suggests, or read semaphor_get_dataset_schema |
relationship_missing | A card's datasets aren't related in the semantic model, so the card can't run; details.unreachableDatasets names the datasets it can't reach | Group by a field of a related dataset, add the missing relationship with relationship.add, or build the card from SQL |
calculated_field_name_taken | calculation.add names a calculated field the dashboard has, or a field of the dataset | Pick another name |
invalid_calculation | The formula doesn't compile or doesn't run on the connection; the message says why | Fix the formula |
calculated_field_not_found | calculation.update or calculation.remove names a field the dashboard doesn't have | Use a name from the outline's calculatedFields |
calculated_field_in_use | calculation.remove names a field a card or filter still uses; details.usedBy lists them | Take it off those cards earlier in the proposal |
calculated_field_not_for_matrix | A Matrix query names one of the dashboard's calculated fields | Use a domain calculation, or build it in the editor |
card_not_editable, filter_not_editable | The outline marks it read only, or the change wouldn't take effect | Follow the fix; change it in the editor; removing it still works |
type_not_supported | The query doesn't fit the card type | Use a type the query fits, or send a complete query with the type change |
query_form_mismatch | A query patch changes form (metric, records, SQL) without a complete query, or mixes keys of two forms | Send the complete query of the new form |
capability_required | The change needs SQL and the session can't use SQL | Use a dataset query, or ask an admin for SQL access |
document_invalid | The changed dashboard wouldn't save, for example a filter mapped to a field you can no longer use | Change the proposal, or read the outline and propose again |
proposal_not_found | Unknown or expired proposalId, or another user's proposal | Propose again |
proposal_stale | The dashboard or a library visual it shows changed after the preview; a value a semantic model change replaces was changed since the preview, or the domain was saved during the apply; or the proposal was made with dashboard.generate, which create replaces | Read it again and propose again |
dashboard_on_watch_page | The dashboard is open on the user's watch page, where the user saves changes | Don't apply. A change proposed while the page was open is already on it; otherwise propose it again. The user can press Stop watching to have you save |
apply_in_progress | The first apply is still running | Retry the same call |
apply_outcome_unknown | The first apply never recorded a result | Check with howToCheck before proposing again |
apply_failed | The apply failed for another reason, and nothing was saved | Read the message; propose again |
Warnings
Warnings come back in warnings on a proposal or an apply. They don't stop anything; show them to the user.
| Warning | When |
|---|---|
type_change_drops | A type change dropped settings the new type can't use; it lists them |
label_kept_after_change | A custom column label was kept after its field's aggregate or grain changed, and may no longer fit |
filter_not_reaching_cards | A filter doesn't reach some cards on its sheets; it lists them with suggestedFields to bind |
repeated_card_condition | The same condition is on every card a filter on its field would reach; it names the cards and the changes that make it one filter's default |
card_condition_repeats_filter_default | A card's own condition repeats the default of a filter that reaches it, so the card won't follow that filter |
detaches_linked_visual | Changing the card, or the spot it's in for tabs, makes a library visual's card local to the dashboard |
tabs_show_as_kpi_info | layout.tabs: a text card in a KPI's spot shows as the KPI's info, not as a tab |
control_binding_dropped | Controls bound to levels or measures the change removes stop changing the card; details.controlIds lists them |
relationship_warning | relationship.add: something the domain reported when the relationship was saved |
commit_failed | Apply: the change was saved, but the commit the project requires failed |
apply_not_recorded | Apply: the change was saved, but its result couldn't be recorded. A retry reports apply_outcome_unknown; don't propose the change again. |
Permission and Approval
These are two different things.
- Permission is enforced by Semaphor on every call: the
mcp:writescope, your role, the per-change rule above, and your permissions on the dashboard or project. - Approval of a particular change happens in your client, before it calls
semaphor_apply_change.
semaphor_apply_change is marked as destructive and semaphor_propose_change as read only. These MCP annotations are advisory hints: they don't force a confirmation dialog, and Semaphor can't prove that a person saw the preview. What happens before apply runs depends on the client:
| Client | Before semaphor_apply_change runs |
|---|---|
| Claude Code | Asks before an MCP tool runs, unless the tool is already allowed. You can choose "Yes, and don't ask again", or add the tool to permissions.allow (for a server you configured yourself, the rule is mcp__<server>__<tool>). Claude Code doesn't use the annotations to decide. Running with permissions bypassed skips these prompts. In non-interactive claude -p runs, a call that would ask is denied unless --allowedTools or an allow rule covers it. |
| claude.ai | Uses the annotations for default permissions: read-only tools can run without a per-call confirmation, and destructive tools prompt. |
| Codex | Follows your Codex approval settings for MCP tool calls. |
| Headless token | No per-change approval. Minting a token with mcp:write is delegated authority: whoever minted it approved writes in advance. |
For an unattended Claude Code run that should read but never write, allow only the read tools, for example --allowedTools "mcp__semaphor-token__semaphor_analyze,mcp__semaphor-token__semaphor_get_analysis_context", or mint the token without mcp:write. The second is the stronger control, because the server then refuses writes whatever the client does.
See Authentication and Security for more.
Discover and Query
How agents find the right data in your semantic model, then run governed analytics, Matrix windows or SQL.
How Cards Read and Show
Change a card's column headers, number and date formats, hidden columns, widths, total row, data labels, legend, axes, chart variant and highlights, and a dashboard's title, through Semaphor MCP.