Making Changes

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, and add a relationship to a semantic model. Every change goes through two tools: semaphor_propose_change previews it and saves nothing, and semaphor_apply_change saves exactly what was previewed.

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

{ "dashboardId": "d_8f2k", "fields": ["outline"] }

{
  "dashboardId": "d_8f2k",
  "changes": [{
    "op": "card.add",
    "type": "bar",
    "title": "Net weight by yard",
    "query": {
      "domainId": "dom_yard",
      "datasetName": "tickets",
      "measures": ["net_weight"],
      "dimensions": ["yard"],
      "dateField": "ticket_date",
      "timeWindow": { "unit": "day", "value": 30, "anchor": "now" }
    }
  }],
  "rationale": "Yard managers asked for a 30-day view."
}

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

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:

It returns:

{
  "proposalId": "chg_...",
  "expiresAt": "2026-10-16T15:12:00Z",
  "risk": "low",
  "target": { "kind": "dashboard", "dashboardId": "d_8f2k", "title": "Weights", "saveAs": "original" },
  "summary": ["Adds the card \"Net weight by yard\" (bar) to Overview: net weight by yard, last 30 days. The dashboard's \"Yard\" filter applies to it."],
  "changes": [
    { "index": 0, "op": "card.add", "ref": "$card_1", "title": "Net weight by yard",
      "sentence": "Adds the card \"Net weight by yard\" (bar) to Overview: net weight by yard, last 30 days. The dashboard's \"Yard\" filter applies to it." }
  ],
  "warnings": [],
  "preview": {
    "cards": [
      { "ref": "$card_1", "title": "Net weight by yard",
        "columns": [{ "name": "yard", "label": "Yard" }, { "name": "net_weight", "label": "Net weight" }],
        "rows": [["CMR", 412880], ["NWY", 288104], ["EST", 190455]], "rowCount": 3 }
    ]
  },
  "next": "Show the summary to the user. After they confirm, call semaphor_apply_change with proposalId \"chg_...\"."
}

• 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 "$yard" 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.

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:

• 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 same windows as semaphor_analyze.
• 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.

{
  "dashboardId": "d_8f2k",
  "changes": [
    { "op": "card.update", "cardId": "c_trend", "type": "line", "title": "Weekly weight", "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:

{
  "dashboardId": "d_8f2k",
  "changes": [{
    "op": "card.add", "type": "kpi", "title": "Net weight, last 30 days",
    "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"],
               "dateField": "ticket_date", "timeWindow": { "unit": "day", "value": 30, "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": "Net weight by region",
      "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"], "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:

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": ["Net weight 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.
• Variables. A text card that shows a filter's value reads it as { "variable": "facility.label" }. A change keeps the card's own variables; add a new one in the editor.
• 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.

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 time window for a date filter.

{
  "dashboardId": "d_8f2k",
  "changes": [
    { "op": "filter.add", "handle": "$yard", "label": "Yard", "domainId": "dom_yard", "datasetName": "tickets",
      "field": "yard", "selection": "single", "defaultValues": ["CMR"] },
    { "op": "filter.bind", "filterId": "$yard", "cardId": "c_scale", "field": "yard_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 default the picker would narrow is refused with filter_not_editable and a fix. A relative default runs to now, so one anchored to the latest available data is refused.
• 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.

What can be changed

The outline marks each card and filter editable. A card that isn't carries notEditable.reason:

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": "Weights",
    "updatedAt": "2026-10-16T14:02:11.420Z",
    "access": { "canEdit": true, "canCopy": true },
    "datasets": [{ "domainId": "dom_yard", "datasetName": "tickets" }],
    "sheets": [
      {
        "sheetId": "s_overview", "title": "Overview", "kind": "dashboard",
        "cards": [
          { "cardId": "c_total", "title": "Net weight", "type": "kpi", "editable": true,
            "source": { "kind": "semantic", "domainId": "dom_yard", "datasetName": "tickets" },
            "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"] } },
          { "cardId": "c_trend", "title": "Weight by day", "type": "line", "editable": true,
            "source": { "kind": "semantic", "domainId": "dom_yard", "datasetName": "tickets" },
            "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"],
                       "dateField": "ticket_date", "timeGrain": "day" } },
          { "cardId": "c_notes", "title": "Notes", "type": "text", "editable": true,
            "text": [{ "type": "paragraph", "content": ["Weights for ", { "variable": "yard.label" }, "."] }] }
        ],
        "layout": [
          { "tiles": [{ "cardIds": ["c_total"], "width": "full" }] },
          { "tiles": [{ "cardIds": ["c_trend"], "width": "half" }, { "cardIds": ["c_notes"], "width": "half" }] }
        ]
      }
    ],
    "filters": [
      { "filterId": "f_yard", "label": "Yard", "editable": true, "domainId": "dom_yard", "datasetName": "tickets",
        "field": "yard", "selection": "multiple", "sheetIds": "all",
        "reaches": ["c_total", "c_trend"], "excluded": [], "notReached": [] }
    ]
  }
}

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": "Weights", "updatedAt": "2026-10-16T14:20:03.114Z",
              "url": "https://semaphor.cloud/project/p_.../dashboard/d_8f2k" },
  "created": [{ "handle": "$yard", "kind": "filter", "id": "f_91c2", "title": "Yard" }],
  "summary": ["Adds the filter \"Yard\" on every sheet, single select, default CMR."],
  "warnings": []
}

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.

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: semaphor_get_dashboard_details returns watchUrl, the link, and watching, true while the user's watch page is on, in logged-in sessions. While it's true, semaphor_propose_change puts the change on the page and returns delivery with what became of it; follow its next and don't apply. 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.

{
  "projectId": "p_...",
  "create": { "title": "Yard 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": ["Yard review"] }, { "type": "paragraph", "content": ["Figures update daily."] }] },
    { "op": "card.add", "handle": "$total", "sheetId": "$overview", "type": "kpi", "title": "Net weight",
      "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"] } },
    { "op": "card.add", "handle": "$trend", "sheetId": "$overview", "type": "line", "title": "Net weight by week",
      "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"], "dateField": "ticket_date", "timeGrain": "week" } },
    { "op": "layout.tabs", "cardIds": ["$trend", "$total"] },
    { "op": "card.add", "sheetId": "$detail", "type": "table", "title": "By yard",
      "query": { "domainId": "dom_yard", "datasetName": "tickets", "measures": ["net_weight"], "dimensions": ["yard"] } },
    { "op": "filter.add", "label": "Yard", "domainId": "dom_yard", "datasetName": "tickets", "field": "yard", "sheetIds": ["$overview", "$detail"] }
  ]
}

• The preview is real. The proposal's first sentence says the whole (Creates a private dashboard "Yard 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.

Add a Relationship

relationship.add adds a relationship between two datasets of a domain, so queries can join them:

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

The relationship is validated when you propose. If a field doesn't exist, or the domain isn't one you can open, propose returns invalid_change and stores nothing; if your role or organization can't change the domain, it returns not_permitted. If someone edits the domain between your preview and your apply, apply returns proposal_stale. A relationship apply returns target: { "kind": "domain", "domainId" } and an empty created.

Retries

semaphor_apply_change is safe to retry with the same proposalId. A change is never applied twice.

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.

Warnings

Warnings come back in warnings on a proposal or an apply. They don't stop anything; show them to the user.

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:

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.