MCP Overview

Change kinds

• Dashboard changes: card.add, card.update, card.remove, the filter.* changes, sheet.add, sheet.update, layout.tabs, layout.untab and layout.arrange, on a dashboard you can edit, or as your own private copy. Organization authors and end users with the Power User role.
• A new dashboard: create in place of dashboardId, with the changes that fill it, saved private to you. Anyone who can create dashboards in the project.
• A semantic model's own changes: domain.update, dataset.update, field.update, metric.update, calculation.add and relationship.update add synonyms, example questions and instructions, change descriptions, labels and formats, add calculations and change definitions. See Improve a Semantic Model.
• relationship.add: adds a relationship between two datasets. Every query on the domain can use it, so it needs the Author role or higher in the project's organization, logged in or with a token, as every semantic model change does.

Permission is not approval

The server enforces permission: write scope, an Author role, the credential rule for each kind, and project access. Approval is the client's job: the apply tool is marked destructive, so clients that honor annotations ask you before running it. For automation tokens, minting write scope is the approval.

Connect an agent with a token

Mint a token on your server:

{
  "projectId": "p_...",
  "projectSecret": "...",
  "orgUserId": "...",
  "mcp": { "scopes": ["mcp:read"], "sql": true },
  "tokenExpiry": 3600
}

Connect any client that takes a header:

{
  "mcpServers": {
    "semaphor": {
      "type": "http",
      "url": "https://semaphor.cloud/api/mcp",
      "headers": { "Authorization": "Bearer ${SEMAPHOR_MCP_TOKEN}" }
    }
  }
}

What to expect

• semaphor_get_access_context answers "why is this tool missing": mode, credential, scopes and whether SQL is on.
• Results are JSON by default and arrive as structured content, checked against each tool's output schema.
• Errors carry a stable code your code can branch on.
• A misspelled argument fails with its name instead of being silently dropped.

Error codes worth knowing