Authentication and Security

Every MCP query passes through the same security enforcement as your dashboards. Semaphor builds a caller profile from the credential on each request, then applies your existing policies, with no MCP-specific configuration.

Credentials

Semaphor MCP accepts two credentials, sent on every request as Authorization: Bearer <token>. Which one you use depends on who is calling.

Hiding a tool from a caller is for clarity, not the security control. The server still authorizes every call against the caller's role, scopes and permissions.

OAuth Login

People in an MCP client sign in with their Semaphor account in the browser, and the client stores and refreshes the login. OAuth login is for organization users. See Connect an AI Client for each client's steps.

Scopes

A client that doesn't ask for a scope gets mcp:read only. To use the change tools, the client must request mcp:read mcp:write at login. Write scope is never enough on its own: the change tools also need an Author role or higher, and your permissions still decide what you can change.

OAuth Endpoints

Most clients discover these from the server's metadata. They're listed for client developers; on a self-hosted install, replace https://semaphor.cloud with your Semaphor URL.

MCP Project Tokens

Automation and agents in your product use a short-lived token your backend mints with the project secret. Minting, request fields and mint errors are on Connect with a Token.

Isolation

Security Policies

Semaphor enforces three layers of policy on every query, from every query tool, including semaphor_query_sql_advanced:

Two callers can get different numbers for the same question. That's expected: each sees only their own data.

SQL Access

SQL and physical table discovery reach your database more directly than the semantic model, so they're limited:

• Organization users need an Author role or higher. Viewers stay on the semantic model.
• Tenant users have SQL unless the token turns it off.
• Any token minted with "mcp": { "sql": false } has no SQL or physical discovery.

Some tools every caller sees also accept arguments that reach physical tables, such as physical mode on semaphor_get_dataset_schema. Without SQL access, those arguments return capability_required, and the semantic form of the tool keeps working.

Semantic Domain Access

When you mint a token, semanticDomainAccess controls which semantic domains the agent can see:

{
  "projectId": "p_...",
  "projectSecret": "<project-secret>",
  "tenantId": "tenant_123",
  "endUserEmail": "maria@acme.com",
  "mcp": { "scopes": ["mcp:read"] },
  "semanticDomainAccess": { "mode": "include", "domains": ["sales", "marketing"] }
}

A token whose domain access excludes every domain doesn't fall back to physical tables: semaphor_get_analysis_context reports recommendedPath: "restricted".

Permission and Approval

Writes raise two separate questions: may this caller write, and has someone approved this particular change?

Headless write tokens are delegated authority. Minting a token with mcp:write approves that automation's writes in advance, with no per-change human approval. Grant write scope only to jobs that need it, with the shortest practical tokenExpiry.

Session Security

• Logins are tied to the user's Semaphor account. The transport is stateless, and project access is checked on every call.
• Tokens are signed, carry their project, identity, scopes and SQL setting, and expire within 24 hours. A token that fails verification gets 401 with "MCP project token is invalid or expired."
• Proposals live 30 minutes and can only be applied by the user who proposed them, in the same project.

Best Practices

• Grant read unless you need writes. Add mcp:write only for automation that creates dashboards.
• Turn off SQL for end users who don't need it. Set "sql": false so the agent stays on the semantic model.
• Limit domains. Use semanticDomainAccess to show the agent only the domains it needs.
• Keep tokens short-lived. Mint per job or per user session, with the shortest tokenExpiry that works.
• Prefer semaphor_analyze. It uses governed semantic domains, relationship diagnostics, and all three policy layers.
• Store secrets safely. Use environment variables or a secret manager, never commit tokens or project secrets, and keep MCP traffic on HTTPS.