Connect an AI Client

Connect your AI client to Semaphor and ask questions about your analytics. You log in once with your Semaphor account, and the agent works across every project you belong to, with your role and permissions.

You need a Semaphor account (organization user) with access to at least one project. For automation or an agent inside your own product, use a token instead: see Connect with a Token.

Pick Your Client

Claude Code

claude plugin marketplace add semaphor-analytics/agent-plugin
claude plugin install semaphor@semaphor-analytics

claude plugin marketplace update semaphor-analytics

claude plugin uninstall semaphor@semaphor-analytics
claude plugin install semaphor@semaphor-analytics

claude plugin uninstall semaphor@semaphor-analytics
claude plugin marketplace remove semaphor-analytics

Codex

codex plugin marketplace add semaphor-analytics/agent-plugin
codex plugin add semaphor@semaphor-analytics

codex mcp login semaphor

codex plugin list --marketplace semaphor-analytics
codex mcp list

codex plugin marketplace upgrade semaphor-analytics

codex plugin remove semaphor@semaphor-analytics
codex plugin add semaphor@semaphor-analytics

codex plugin remove semaphor@semaphor-analytics
codex plugin marketplace remove semaphor-analytics

claude.ai

Custom connectors need a Claude plan that supports them.

https://semaphor.cloud/api/mcp

ChatGPT

ChatGPT needs developer mode for custom MCP servers.

https://semaphor.cloud/api/mcp

Cursor

{
  "mcpServers": {
    "semaphor": {
      "url": "https://semaphor.cloud/api/mcp"
    }
  }
}

To try what an automation or embedded agent will see, connect Cursor with a token instead: see Connect with a Token.

Ask Your First Question

Start a new conversation and ask:

What data can I analyze in Semaphor?

If you belong to one project, the agent uses it automatically. If you belong to several, it lists them and asks which one you mean, then passes that projectId on each call. To switch, name the other project.

You: "What data can I analyze in Semaphor?"

Agent calls: semaphor_list_projects
Agent: "You have 3 projects: Sales, Marketing and Operations. Which one should I use?"

You: "Sales. How many orders did we get last month?"

Agent calls: semaphor_get_analysis_context with projectId "p_abc123"
Agent calls: semaphor_list_semantic_domains, semaphor_list_datasets
Agent calls: semaphor_get_dataset_schema with datasetName "orders"
Agent calls: semaphor_analyze with a previous-month timeWindow
Agent: "You received 4,328 orders last month, up 12% from the month before."

You: "Break that down by region"

Agent calls: semaphor_analyze with region as a dimension
Agent: "West: 1,456 (34%), East: 1,198 (28%), Central: 892 (21%), South: 782 (18%)"

Other questions to try:

How did revenue change last quarter, and what drove it?
Which regions are behind target this month?
Check whether my sales dashboard's numbers are right.

See Discover and Query for how the agent finds the right data.

Read and Write Access

A login grants read access by default: discovery, queries and dashboards. To let the agent create dashboards or add relationships to a semantic model, you need both:

• An organization role of Author or higher
• The mcp:write scope, which your client asks for when it requests mcp:read mcp:write at login

Without both, the change tools don't appear. Every change is previewed before it's applied: see Making Changes.

Self-Hosted Semaphor

On a self-hosted install, use your Semaphor URL followed by /api/mcp wherever this page uses https://semaphor.cloud/api/mcp.

If Something's Missing

• The tools don't appear: restart the client (/reload-plugins in Claude Code), then check /mcp or codex mcp list for the semaphor server.
• The server needs a login: complete it with /mcp in Claude Code or codex mcp login semaphor in Codex.
• A tool you expected is missing: ask the agent to call semaphor_get_access_context. It reports your access mode, scopes and whether SQL is available.

See Troubleshooting for more.