Semaphor
MCP

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.

propose_changesaves nothingproposedexpires in 30 minapplyingone writer at a timeappliedresult recordedfailednothing writtenapplyretry: sameresulttarget changed: proposal_stale, propose again
A proposal saves nothing and expires after 30 minutes. A retry of an applied proposal returns the recorded result instead of writing twice.

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.

Read 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.

Propose: add a bar chart
{
  "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.

Apply
{ "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.

ChangeLogged in (OAuth)Automation tokenEnd-user token (Power User)
Dashboard cards, filters, sheets, tabs, text cards, layout and calculated fieldsYesYesYes, on dashboards they can edit in their own tenant
A new dashboard (create)YesYesYes, 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)YesYesNo
relationship.addYesYesNo

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:

ArgumentRequiredDescription
dashboardIdFor changes to a dashboardThe dashboard to change
createFor a new dashboard{ "title", "description" } in place of dashboardId: the changes build a new private dashboard. See Build a New Dashboard.
domainIdFor semantic model changesThe semantic domain to change. With dashboard changes it is ignored: each card query and filter names its own domain.
changesYes1 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.
saveAsNo"original" (default) or "copy": save the changes as your own private copy
previewNo"sample" (default, up to 5 rows per changed card), "rows" (up to 50) or "none"
includeNo["outline"] also returns the dashboard's outline as it will be after the changes, as proposedOutline
rationaleNoWhy the change is needed, in up to 500 characters. It's kept with the proposal.
projectIdNoInteractive sessions pass the project for create and semantic model changes; dashboard changes use the dashboard's own project

It returns:

Propose response
{
  "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_...\"."
}
FieldWhat it holds
proposalIdThe ID to apply. Proposals expire at expiresAt, 30 minutes after proposing.
risklow 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
summaryOne sentence per change, in order. Show these to the user.
confirmnot_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.
changesThe same sentences with each change's index, op, ref (its handle or ID) and title, and the ruleId a highlight.add creates
warningsThings the proposal does that the user should know about. See Warnings.
preview.cardsUp 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.skippedChanged cards beyond the first 5, not run
preview.failedCards that didn't run: { ref, title, code, message }. The proposal still stands, so fix the query or apply anyway.
proposedOutlineWith include: ["outline"]: the outline as it will be after the changes
nextWhat 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.add or sheet.add a handle such as "$region" and use it in later changes of the same list wherever a card, filter or sheet ID goes, except in card.remove and filter.remove. A sheet's handle goes in card.add's sheetId, a filter's sheetIds and layout.arrange. A card.add without one gets $card_1, $card_2 and 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.

ChangeFields
card.addtype, title, and query, or text for a text card; optional handle, sheetId, description, matrix, width, position, and the card settings below
card.updatecardId; 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.removecardId
filter.addlabel, domainId, datasetName, field; optional handle, selection, showAs, defaultValues, defaultCondition, defaultPeriod, sheetIds, or cardId and position to pin it on a card
filter.updatefilterId; 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.removefilterId
filter.bindfilterId, cardId, field: the field of that card's dataset the filter applies through
filter.excludefilterId, cardId: stops the filter applying to that card
layout.arrangeoptional sheetId, keepOrder
layout.tabscardIds: two or more cards on one sheet, the first shown
layout.untabcardId: a card in tabs, given its own spot
sheet.addtitle; optional handle
sheet.updatesheetId, title
highlight.addcardId, column, and when with color, or scale, or bars; optional apply
highlight.removecardId, ruleId
dashboard.updateoptional 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" }:

Operatorvalues
between, not_betweentwo numbers, low then high
>=, <=, >, <, =, !=one number
is_null, is_not_nullnone
Add a range filter that opens at 500 or more
{ "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:

  • showAs other than "range" or "list", or on a field that isn't a number;
  • defaultCondition on a list or a date filter, null included (clear a list's default with defaultValues: null);
  • defaultValues on 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 than operator and values.

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:

FormFields
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, MEDIAN or DISTINCT. "__count" counts rows.
  • timeGrain is minute, hour, day, week, month, quarter or year.
  • timeWindow takes the semaphor_analyze windows 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" }. A rolling window in days or longer is refused, and its fix offers 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.
  • filters are { "field", "operator", "values" } with operator one of =, !=, in, not_in, contains, not_contains, between, not_between, >, >=, <, <=, is_null or is_not_null. Add "scope": "aggregate" to filter a measure after it's aggregated.
  • orderBy is { "field", "direction": "asc" | "desc" }. limit is 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.

Make a card a weekly line chart and rename it
{
  "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:

FieldValues
widthfull, 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
A KPI at the top, full width
{
  "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.

Tidy the only grid sheet
{ "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:

A Regions sheet with a chart on it
{
  "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.

Two charts as tabs, the monthly one first
{ "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:

BlockFields
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:

A text card with a heading, a bold figure, a link and a list
{
  "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 from bold, italic and link. 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 editorOnly and kept.
  • A text card's words change with card.update's text; its title and description (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):

The total net purchase value, compared with the period before
{
  "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" } }] }
}
getQueryShows
onlyone dimensionThe value when exactly one row matches; nothing when more do
firstone dimension and orderByThe first value by that order
list, or { "kind": "list", "limit", "separator" }one dimensionThe distinct values, joined
aggregateone measure with its aggregateOne 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:

Up or down by the percent change, in red when down
{ "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:

A fallback when no contact is on file
{ "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.

A filter that also reaches a card on another dataset
{
  "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 with suggestedFields from the domain's relationships. Add a filter.bind with 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, month or range). 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 with filter_not_editable and a fix.
  • A defaultPeriod moves 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 a fix.
  • 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 carries defaultPeriodReadOnly: the refusal a write of it would get, with the windows that can replace it. It stays as long as filter.update leaves defaultPeriod out.
  • 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 fix says 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.

Pin a Region filter first on a table
{ "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 its filterId, field and default. filter.update and filter.remove take that filterId, and the card's id as cardId; filter.update with position moves it.
  • Copies of one visual (a duplicated sheet keeps a linked visual's filters) share pinned filter ids. Send cardId to name which card's filter you mean: an id on more than one card without it is refused, naming the cards, and so is a cardId whose 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. sheetIds with a cardId is 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.

ChangeDoes
calculation.addAdds 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.updateChanges 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.removeRemoves 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.

Propose: export duration in seconds
{
  "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:

ReasonThe card
textA text card whose words come from a query
document_sectionA card in a Document section
customA custom visual
needs_sql_accessA SQL card, for a session that can't use SQL
type_not_supportedA 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_expressibleUses 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.

An outline (shortened)
{
  "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": [] }
    ]
  }
}
FieldWhat it holds
updatedAtWhen the dashboard was last saved. An apply checks it: a newer save means proposal_stale.
accesscanEdit: change it in place. canCopy: you can't edit it but can save a private copy with "saveAs": "copy".
datasetsEvery dataset a card or filter uses
sheets[].kinddashboard (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[].layoutGrid 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
truncatedPresent 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:

Apply response
{
  "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": []
}
FieldWhat it holds
appliedtrue when the change was saved
replayedtrue when this is the recorded result of an earlier apply of the same proposal
targetThe dashboard (or domain) changed, with its new updatedAt. url opens it in Semaphor, for organization users. A copy adds copiedFrom.
createdWhat 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" }
summaryThe sentences that were applied
warningsAnything 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.

Propose: a new dashboard with two sheets, tabs, a text card and a filter
{
  "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 target is the new dashboard; organization users get its url, and created lists 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 a dashboard.update in a new dashboard's changes is refused. More than 50 changes are refused with too_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.

ChangeNamesChanges
domain.updatethe domain (domainId)label, description, context
dataset.updatedatasetlabel, description, context
field.updatedataset, fieldlabel, 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.updatemetric, and its dataset unless it spans datasetslabel, 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 fieldDoes
instructionsReplaces the instructions; null clears them
synonyms{ "add": [...], "remove": [...] }. A synonym already there, in any case, is skipped; removing one that's gone does nothing.
examplesExample questions, { "add": [...], "remove": [...] }, the same way
Propose: other names and a description for a field
{
  "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.

Its summary
["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 name is refused with "Change the label instead."
  • null clears 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_stale and saves nothing. Its changed lists each value as { "what", "now" } in the readback's words, such as Orders · Amount description and "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:

ChangeChanges
field.update with expressionA calculated field's formula. A field that reads a column has no formula: add a calculation instead.
metric.update with expressionA metric's formula, for a metric on one dataset
field.update with defaultAggregateThe aggregate a fact starts with on a card: SUM, COUNT, AVG, MIN, MAX, MEDIAN or DISTINCT
field.update with granularityThe grain a date dimension groups by, such as month; null removes it
dataset.update with primaryDateFieldThe dataset's default date, a date dimension's name; null removes it
relationship.updateNames a relationship by its name or id; isActive: false turns it off, defaultJoinType is LEFT or INNER, and description and context change as above
Its summary: a metric's formula
["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.

FieldValues
nameThe new calculation's name, not used by another field or metric on its dataset
expressionIts formula
datasetFor a formula over one dataset's fields
inputsFor a metric across datasets: each {token} in the formula to { "dataset", "field", "aggregate" } or { "metric", "dataset" }
useFor a row formula: aggregate (default) adds a fact; group_or_filter adds a dimension
label, description, dataTypeOptional
Propose: a new metric
{
  "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:

Propose: add a relationship
{
  "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."
}
FieldValues
fromThe many side: a dataset name and one or more of its fields
toThe other side, usually a key of that dataset
cardinalitymany_to_one or one_to_one
defaultJoinTypeLEFT or INNER
descriptionOptional

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:

statusMeaning
addedSaved. All the added relationships are saved together.
existingAn equivalent relationship was already in the domain, for example added on the domain page since your preview. Nothing to do.
refusedNo 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
SucceededThe recorded result again, with replayed: true
FailedThe recorded error. Propose again if you still want the change.
Is still runningapply_in_progress. Retry the same call shortly.
Started over 5 minutes ago and never recorded a resultapply_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.

CodeMeaningWhat to do
write_scope_requiredThe session doesn't have mcp:write; the error lists requiredScope and grantedScopesLog in with write access, or mint a token with mcp:write
invalid_changeA change doesn't match the tool's fields, more than 5 relationship.add in one proposal, or the same relationship twiceFix the fields named in problems
too_many_changesMore than 20 changes for a dashboard or a semantic model, or 50 for a new dashboardSplit them across proposals
invalid_change_targetThe target doesn't fit the changesDashboard 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_requiredYou can view the dashboard but not edit itPropose again with "saveAs": "copy"
not_permittedYou 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 itAsk an admin for access
project_not_foundThe projectId for create or relationship.add isn't one you can reachUse a project from semaphor_list_projects
dashboard_not_foundThe dashboard doesn't exist, or you can't open itFind it with semaphor_list_dashboards
card_not_found, filter_not_found, sheet_not_foundAn ID isn't on this dashboard; position.after names a card that isn't on a grid sheetRead the outline again and use its IDs
handle_unknownA handle is used before a change defines itDefine the handle in an earlier change, or use an ID
sheet_requiredThe dashboard has several grid sheets and card.add or layout.arrange named nonePick one of the sheets the error lists
sheet_not_a_gridThe sheet is a Document, or the dashboard has no grid sheet, so it takes no card and can't be arrangedUse a grid sheet from the outline, or add one with sheet.add earlier in the list
layout_invalidlayout.tabs names one card, cards on two sheets, a card in a Document section, or a custom visual's inputName two or more cards of one grid sheet
text_invalidA 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_foundA field isn't in the datasetUse one of the fields the error suggests, or read semaphor_get_dataset_schema
relationship_missingA card's datasets aren't related in the semantic model, so the card can't run; details.unreachableDatasets names the datasets it can't reachGroup by a field of a related dataset, add the missing relationship with relationship.add, or build the card from SQL
calculated_field_name_takencalculation.add names a calculated field the dashboard has, or a field of the datasetPick another name
invalid_calculationThe formula doesn't compile or doesn't run on the connection; the message says whyFix the formula
calculated_field_not_foundcalculation.update or calculation.remove names a field the dashboard doesn't haveUse a name from the outline's calculatedFields
calculated_field_in_usecalculation.remove names a field a card or filter still uses; details.usedBy lists themTake it off those cards earlier in the proposal
calculated_field_not_for_matrixA Matrix query names one of the dashboard's calculated fieldsUse a domain calculation, or build it in the editor
card_not_editable, filter_not_editableThe outline marks it read only, or the change wouldn't take effectFollow the fix; change it in the editor; removing it still works
type_not_supportedThe query doesn't fit the card typeUse a type the query fits, or send a complete query with the type change
query_form_mismatchA query patch changes form (metric, records, SQL) without a complete query, or mixes keys of two formsSend the complete query of the new form
capability_requiredThe change needs SQL and the session can't use SQLUse a dataset query, or ask an admin for SQL access
document_invalidThe changed dashboard wouldn't save, for example a filter mapped to a field you can no longer useChange the proposal, or read the outline and propose again
proposal_not_foundUnknown or expired proposalId, or another user's proposalPropose again
proposal_staleThe 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 replacesRead it again and propose again
dashboard_on_watch_pageThe dashboard is open on the user's watch page, where the user saves changesDon'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_progressThe first apply is still runningRetry the same call
apply_outcome_unknownThe first apply never recorded a resultCheck with howToCheck before proposing again
apply_failedThe apply failed for another reason, and nothing was savedRead 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.

WarningWhen
type_change_dropsA type change dropped settings the new type can't use; it lists them
label_kept_after_changeA custom column label was kept after its field's aggregate or grain changed, and may no longer fit
filter_not_reaching_cardsA filter doesn't reach some cards on its sheets; it lists them with suggestedFields to bind
repeated_card_conditionThe 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_defaultA card's own condition repeats the default of a filter that reaches it, so the card won't follow that filter
detaches_linked_visualChanging the card, or the spot it's in for tabs, makes a library visual's card local to the dashboard
tabs_show_as_kpi_infolayout.tabs: a text card in a KPI's spot shows as the KPI's info, not as a tab
control_binding_droppedControls bound to levels or measures the change removes stop changing the card; details.controlIds lists them
relationship_warningrelationship.add: something the domain reported when the relationship was saved
commit_failedApply: the change was saved, but the commit the project requires failed
apply_not_recordedApply: 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:write scope, 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:

ClientBefore semaphor_apply_change runs
Claude CodeAsks 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.aiUses the annotations for default permissions: read-only tools can run without a per-call confirmation, and destructive tools prompt.
CodexFollows your Codex approval settings for MCP tool calls.
Headless tokenNo 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.

On this page