MCP Server

Overview

Oxygen’s MCP server exposes your data resources as tools that can be called by AI assistants and other MCP clients. This enables seamless integration between your structured data operations and conversational AI interfaces.

Starting the MCP Server

Oxygen supports two transport options for the MCP server:

SSE (Server-Sent Events)

To run the MCP SSE server use the oxy mcp sse command:

oxy mcp sse <project-path> --port <port>

Stdio

Start the server with stdio transport:

oxy mcp stdio <project-path>

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "oxy": {
      "command": "oxy",
      "args": ["mcp", "stdio", "/path/to/your/project"],
      "env": {
        "OPENAI_API_KEY": "<your_model_api_key>"
      }
    }
  }
}

Configuring Resource Exposure

By default, Oxygen exposes all automations in your project as MCP tools. You can customize which resources are exposed by adding an mcp section to your config.yml:

mcp:
  tools:
    - semantics/topics/*.topic.yml
    - automations/*.automation.yml
    - data/*.sql

Supported resource types: automations (.automation.yml, .procedure.yml), semantic topics (.topic.yml), and SQL files (.sql). Other files matched by a pattern are skipped. Supported patterns:

Direct file paths: automations/monthly-report.automation.yml
Glob patterns: automations/*.automation.yml, semantics/**/*.topic.yml
Multiple resource types in a single configuration

Configuration behavior:

When mcp.tools is defined: Only specified resources are exposed
When mcp.tools is omitted: All automations are exposed by default
Empty mcp.tools list: No tools are exposed

Agents are not exposed over MCP. To make an agent’s work available to an MCP client, wrap it in an automation with an agent task.

Resource Types

Automations

Automations are exposed as MCP tools that run the automation and return its results. Tool naming: workflow-{name}, where {name} is the automation’s file name up to the first dot (monthly-report.automation.yml becomes workflow-monthly-report) Input schema:

{
  "variables": "object (optional) — values for the automation's variables"
}

Example:

{
  "name": "workflow-monthly-report",
  "arguments": {
    "variables": {
      "month": "2024-11",
      "metric": "revenue"
    }
  }
}

SQL Files

SQL files (.sql) can be exposed as executable tools. Tool naming: sql-{filename_without_extension} Input schema:

{
  "database": {
    "type": "string",
    "description": "Database connection to use (optional)"
  }
}

SQL file description: Add a description comment at the top of your SQL file:

-- Description: Calculate monthly revenue by product category

SELECT
  category,
  SUM(amount) as total_revenue
FROM sales
GROUP BY category;

Example tool call:

{
  "name": "sql-monthly-report",
  "arguments": {
    "database": "analytics"
  }
}

Semantic Topics

Semantic topics from your semantic model can be exposed as structured query tools. Tool naming: semantic-{topic_name} Input schema:

{
  "dimensions": ["string"],
  "measures": ["string"],
  "filters": [{ "field": "string", "op": "string", "value": "any" }],
  "time_dimensions": [{ "dimension": "string", "granularity": "string" }],
  "limit": "number",
  "order_by": [{ "field": "string", "direction": "asc|desc" }],
  "variables": { "type": "object" }
}

Example:

{
  "name": "semantic-sales-analytics",
  "arguments": {
    "dimensions": ["products.category", "time.month"],
    "measures": ["sales.total_revenue", "sales.order_count"],
    "filters": [
      {
        "field": "time.year",
        "op": "eq",
        "value": 2024
      }
    ],
    "limit": 100
  }
}

Advanced Features

Session Filters

Session filters enable row-level security and data filtering across all tool types. They are passed via the _meta parameter according to the MCP specification. Example:

{
  "name": "semantic-team-performance",
  "arguments": {
    "measures": ["sales.total_revenue"],
    "dimensions": ["sales.rep_name"]
  },
  "_meta": {
    "filters": {
      "user_id": "user_123",
      "organization_id": "org_456",
      "region": "US"
    }
  }
}

Behavior:

Filters are validated against your project’s filter schema (defined in config.yml)
Invalid filter keys or types return errors before execution
Missing required filters cause validation errors
Missing optional filters use schema defaults
Filters apply to all data operations within the tool execution

Connection Overrides

Connection overrides allow runtime modification of database connection parameters for multi-tenant applications or dynamic routing. Example:

{
  "name": "sql-customer-report",
  "arguments": {
    "variables": {
      "customer_id": "12345"
    }
  },
  "_meta": {
    "connections": {
      "analytics": {
        "database": "customer_12345_db",
        "schema": "reporting"
      }
    }
  }
}

Variables via Meta

Variables can be passed via _meta and are merged with tool arguments using a defined precedence order. Merging order (later overrides earlier):

Default values from tool definition
Variables from tool arguments
Variables from _meta["variables"]

Example:

{
  "name": "workflow-report",
  "arguments": {
    "variables": {
      "include_tax": false
    }
  },
  "_meta": {
    "variables": {
      "currency": "EUR",
      "organization_id": "org_123"
    }
  }
}

Get started

Data Infrastructure

World Model

Agentic Intelligence

Custom Apps

Automations

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

MCP Server

Overview

Starting the MCP Server

SSE (Server-Sent Events)

Stdio

Configuring Resource Exposure

Resource Types

Automations

SQL Files

Semantic Topics

Advanced Features

Session Filters

Connection Overrides

Variables via Meta

​Overview

​Starting the MCP Server

​SSE (Server-Sent Events)

​Stdio

​Configuring Resource Exposure

​Resource Types

​Automations

​SQL Files

​Semantic Topics

​Advanced Features

​Session Filters

​Connection Overrides

​Variables via Meta

Overview

Starting the MCP Server

SSE (Server-Sent Events)

Stdio

Configuring Resource Exposure

Resource Types

Automations

SQL Files

Semantic Topics

Advanced Features

Session Filters

Connection Overrides

Variables via Meta