Interactive MCP Quick Start

Connect your personal AI assistant to Semaphor and ask questions about your analytics data using natural language.

Prerequisites

A Semaphor account (organization user)
An MCP-compatible AI client (Claude, Cursor)
At least one project with data connections configured

Step 1: Connect Your AI Client

How you connect depends on your AI client:

Client	Connection Method	Guide
Claude	OAuth (automatic)	Claude Setup
Cursor	mcp-remote (manual config)	Cursor Setup
Custom	HTTP + Bearer token	Programmatic Access

For the quickest setup, Claude handles the OAuth flow automatically — you just click "Sign in" when prompted.

Step 2: Discover Your Projects

After connecting, ask your AI to list your available projects:

Discovering projects

You: "List my Semaphor projects"

AI calls: semaphor_list_projects
AI: "You have 3 projects:
     1. Sales Dashboard (p_abc123)
     2. Marketing Analytics (p_def456)
     3. Engineering Metrics (p_ghi789)"

Interactive Sessions Require a Project ID

Unlike embedded MCP (where the project token already carries the project scope), interactive OAuth sessions don't have a fixed project. After discovering your projects, tell your AI which one to use — it will pass the projectId automatically on each subsequent tool call.

Step 3: Explore and Query

Tell your AI which project to use and start asking questions. The AI will pass the projectId automatically on each tool call:

Full example session

You: "Use the Sales Dashboard project and show me what data is available"

AI calls: semaphor_get_analysis_context with projectId "p_abc123"
AI: "Your project has a semantic domain called 'Sales Data' with 4 datasets.
     I recommend the semantic discovery path."

You: "What datasets are in Sales Data?"

AI calls: semaphor_list_datasets with projectId "p_abc123", domainId "dom_abc"
AI: "The Sales Data domain has: orders, customers, products, and regions."

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

AI calls: semaphor_get_dataset_schema with projectId "p_abc123", domainId, datasetName
AI calls: semaphor_query_sql with projectId "p_abc123", connectionId, SQL
AI: "You received 4,328 orders last month, up 12% from the previous month."

You: "Break that down by region"

AI calls: semaphor_query_sql with projectId "p_abc123", updated SQL
AI: "Orders by region:
     - West: 1,456 (34%)
     - East: 1,198 (28%)
     - Central: 892 (21%)
     - South: 782 (18%)"

Working with Multiple Projects

To query a different project, just tell your AI and it will pass the new projectId:

Switching projects

You: "Now show me campaign data from the Marketing Analytics project"

AI calls: semaphor_get_analysis_context with projectId "p_def456"
AI: "Marketing Analytics has a semantic domain called 'Campaign Data'..."

No explicit project-switching step is needed — the AI includes the correct projectId on each tool call.

Next Steps

Client Setup Guides — Detailed setup instructions for your specific AI client
Discovery Workflow — Understand how data discovery works
Tools Reference — Full reference for all MCP tools