Tools Reference

Semaphor MCP exposes 12 tools organized into two categories: discovery and query. All tools accept a response_format parameter ("json" or "markdown") to control output formatting.

Discovery Tools

semaphor_get_analysis_context

Bootstrap tool for data questions. Call this first to determine the recommended discovery path (semantic or physical).

Parameters:

Response fields: projectId, recommendedPath, recommendedNextTool, guidance, semanticDomains, fallbackConnections

// Request
{ "name": "semaphor_get_analysis_context", "arguments": {} }

// Response (summarized)
{
  "projectId": "p_abc123",
  "recommendedPath": "semantic",
  "recommendedNextTool": "semaphor_list_semantic_domains",
  "semanticDomains": [
    { "id": "dom_abc", "name": "Sales Analytics", "datasetCount": 4 }
  ]
}

semaphor_get_access_context

Returns the active MCP session context, including user identity, organization, and project scope.

Parameters:

Response fields: actorType, userId, organizationId, projectId, tenantId, authMethod, sessionBound

// Response
{
  "actorType": "organization",
  "userId": "kp_abc123",
  "organizationId": "org_xyz",
  "projectId": "p_abc123",
  "authMethod": "project-token",
  "sessionBound": false
}

semaphor_list_projects

Lists all projects accessible to the authenticated user.

Parameters:

Response fields: Array of projects with id, name, description, owner, createdAt

Use the returned projectId values to pass on subsequent project-scoped tool calls.

semaphor_list_dashboards

Lists dashboards accessible to the authenticated user in a specific project.

Parameters:

Response fields: Array of dashboards with id, title, description, createdAt, updatedAt

// Request
{
  "name": "semaphor_list_dashboards",
  "arguments": { "projectId": "p_abc123", "search": "sales" }
}

semaphor_get_dashboard_details

Returns detailed information about a specific dashboard.

Parameters:

Response fields: id, title, description, sheets, cards, createdAt, updatedAt, and optionally template (full JSON configuration)

semaphor_list_semantic_domains

Lists semantic domains available in the project. Call this when the analysis context recommends the semantic path.

Parameters:

Response fields: Array of domains with id, name, description, connectionId, datasetCount

// Response
{
  "domains": [
    {
      "id": "dom_abc",
      "name": "Sales Analytics",
      "description": "Customer orders and revenue data",
      "connectionId": "conn_123",
      "datasetCount": 4
    }
  ]
}

semaphor_list_datasets

Lists datasets within a semantic domain. Call this after semaphor_list_semantic_domains and before semaphor_get_dataset_schema.

Parameters:

Response fields: Array of datasets with name, label, description, type (physical or virtual)

// Request
{
  "name": "semaphor_list_datasets",
  "arguments": { "domainId": "dom_abc" }
}

// Response
{
  "datasets": [
    { "name": "orders", "label": "Orders", "description": "Customer orders" },
    { "name": "customers", "label": "Customers", "description": "Customer profiles" }
  ]
}

semaphor_get_dataset_schema

Returns columns for a semantic dataset or physical table. Supports two usage patterns.

Semantic mode (preferred): Pass domainId and datasetName.

Physical mode: Pass connectionId and tableName (with optional databaseName and schemaName).

Parameters:

Response fields: Array of columns with name, label, type, fieldType (dimension or measure), description, aggregation

{
  "name": "semaphor_get_dataset_schema",
  "arguments": { "domainId": "dom_abc", "datasetName": "orders" }
}

{
  "name": "semaphor_get_dataset_schema",
  "arguments": {
    "connectionId": "conn_123",
    "schemaName": "public",
    "tableName": "orders"
  }
}

semaphor_list_connections

Lists database connections accessible in the active project. Use this only when the semantic path is unavailable.

Parameters:

Response fields: Array of connections with id, name, type (postgres, mysql, bigquery, etc.)

semaphor_get_domain_relationships

Returns join relationships between datasets in a semantic domain. Useful for multi-dataset queries.

Parameters:

Response fields: Array of relationships with sourceDataset, targetDataset, sourceField, targetField, joinType

{
  "relationships": [
    {
      "sourceDataset": "orders",
      "targetDataset": "customers",
      "sourceField": "customer_id",
      "targetField": "id",
      "joinType": "many_to_one"
    }
  ]
}

Query Tools

semaphor_query_spec

Executes a Semaphor-native card-config query. Uses the same query engine as Semaphor dashboards. Respects all security policies (CLS, SLS, RLS).

Parameters:

Response fields: data (array of records), columns, rowCount, queryTime, sql (generated SQL)

{
  "name": "semaphor_query_spec",
  "arguments": {
    "chartType": "table",
    "connectionId": "conn_123",
    "cardConfig": {
      "dimensions": [{ "column": "region", "dataType": "string" }],
      "metrics": [{ "column": "total_amount", "aggregation": "SUM" }]
    },
    "cardDataSource": {
      "type": "semantic",
      "domainId": "dom_abc",
      "datasetName": "orders"
    }
  }
}

semaphor_query_sql

Executes a SQL-first query for advanced analysis. Respects all security policies (CLS, SLS, RLS).

Parameters:

Response fields: data (array of records), columns, rowCount, queryTime

{
  "name": "semaphor_query_sql",
  "arguments": {
    "connectionId": "conn_123",
    "sql": "SELECT region, COUNT(*) AS orders, SUM(total_amount) AS revenue FROM orders GROUP BY region ORDER BY revenue DESC"
  }
}

Common Parameters

These parameters are shared across most tools: