Embedded MCP Quick Start

Give your SaaS application's AI agents access to Semaphor data in four steps.

Prerequisites

A Semaphor project with at least one data connection
A project token (or the project ID and secret to generate one)
An MCP-compatible AI framework or client

Step 1: Generate a Project Token

Generate a project token from your backend server using the Token API:

Generate a project token

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890",
    "orgUserId": "user_123",
    "tokenExpiry": 3600
  }'

The response includes an accessToken that you'll use to authenticate MCP requests.

Limiting Domain Access

Use semanticDomainAccess to control which semantic domains the AI agent can see. For example, to restrict access to only your sales data:

{
  "semanticDomainAccess": {
    "mode": "include",
    "domains": ["sales_data"]
  }
}

See Token API for all options.

Security

Never expose your projectSecret in client-side code. Always generate tokens from your backend server.

Step 2: Configure Your MCP Client

Add Semaphor as an MCP server in your client configuration. Here's the Cursor setup as a canonical example:

~/.cursor/mcp.json

{
  "mcpServers": {
    "semaphor": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://semaphor.cloud/api/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${SEMAPHOR_AUTH_HEADER}"
      ],
      "env": {
        "SEMAPHOR_AUTH_HEADER": "Bearer YOUR_PROJECT_TOKEN"
      }
    }
  }
}

Replace YOUR_PROJECT_TOKEN with the accessToken from Step 1.

For other clients, see the Client Setup guides. For SDK and API access, see Programmatic Access.

Step 3: Discover Your Data

Once connected, your AI agent should follow this discovery sequence:

Get analysis context — Call semaphor_get_analysis_context to determine whether to use the semantic or physical discovery path
List semantic domains — If the semantic path is recommended, call semaphor_list_semantic_domains
List datasets — Call semaphor_list_datasets to discover datasets within a domain
Get schema — Call semaphor_get_dataset_schema to get columns and types

Here's what a typical conversation looks like:

Example conversation

You: "What data is available in Semaphor?"

AI calls: semaphor_get_analysis_context
AI: "Your project has 2 semantic domains: 'Sales Analytics' and 'Marketing Data'.
     I recommend using the semantic path for discovery."

You: "Show me what's in Sales Analytics"

AI calls: semaphor_list_datasets with domainId
AI: "The Sales Analytics domain has 3 datasets: orders, customers, and products."

You: "What columns does the orders dataset have?"

AI calls: semaphor_get_dataset_schema with domainId and datasetName "orders"
AI: "The orders dataset has columns: order_id, customer_id, order_date,
     total_amount, status, region..."

See Discovery Workflow for a detailed explanation of the semantic-first discovery pattern.

Step 4: Query Data

Use one of two query tools depending on your needs:

Standard Mode — For structured analytics using Semaphor's card-config format. Respects all security policies (CLS, SLS, RLS).

Dev Mode — For semantically grounded SQL queries. Best for complex joins and ad-hoc analysis. Respects all security policies (CLS, SLS, RLS).

Example query

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

AI calls: semaphor_query_sql with:
  connectionId: "conn_abc123"
  sql: "SELECT region, COUNT(*) as order_count
        FROM orders
        WHERE order_date >= date_trunc('month', current_date - interval '1 month')
        AND order_date < date_trunc('month', current_date)
        GROUP BY region
        ORDER BY order_count DESC"

AI: "Here are last month's orders by region:
     - West: 1,247 orders
     - East: 1,103 orders
     - Central: 892 orders
     - South: 786 orders"

See Querying Data for details on both query modes.

Embedded vs Interactive

	Embedded	Interactive
Auth method	Project token	OAuth (Kinde)
Project scope	Fixed by token	Pass `projectId` per call
User types	Org users + tenant users	Org users only
Project listing	Not available	Available
Best for	AI agents in SaaS apps	Personal AI assistants

Next Steps

Discovery Workflow — Understand the semantic-first discovery pattern
Tools Reference — Full reference for all MCP tools
Security — How security policies apply to MCP queries