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), and analyticsRole when authored.

// 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, and metric aggregate metadata when authored.

{
  "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_analyze

Executes governed Semaphor analytics. Use this as the default query tool for semantic metric-by-dimension, top-N, time-series, filters, latest-available windows, period comparisons, period-change driver analysis, and relationship-aware joins. Respects all security policies.

Parameters:

Response fields: data, columns, rowCount, generated sql, executionResult, relationship diagnostics, and time-window/aggregate metadata where applicable.

Comparison behavior follows the shared Metric Comparisons contract. Omit comparison when no comparison is requested.

{
  "name": "semaphor_analyze",
  "arguments": {
    "domainId": "dom_abc",
    "datasetName": "orders",
    "metrics": [{ "datasetName": "orders", "name": "total_amount" }],
    "dimensions": [{ "datasetName": "customers", "name": "region" }],
    "limit": 10
  }
}

{
  "name": "semaphor_analyze",
  "arguments": {
    "domainId": "dom_abc",
    "datasetName": "orders",
    "metrics": [
      { "datasetName": "orders", "name": "gross_margin_value", "aggregate": "AVG" }
    ],
    "primaryMetric": {
      "datasetName": "orders",
      "name": "gross_margin_value",
      "aggregate": "AVG"
    },
    "dimensions": [{ "datasetName": "products", "name": "category" }]
  }
}

semaphor_query_sql_advanced

Executes a SQL-first query for advanced analysis that cannot be expressed through semaphor_analyze. Respects all security policies.

Parameters:

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

{
  "name": "semaphor_query_sql_advanced",
  "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: