> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Learn how to use the Model Context Protocol (MCP) server in Oxygen to expose your data agents, workflows, SQL files, and semantic topics to AI assistants like Claude.

<RewriteBanner />

## 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:

```sh theme={null}
oxy mcp sse --port <port> --project-path <path>
```

### Stdio

Start the server with stdio transport:

```sh theme={null}
oxy mcp stdio <project-path>
```

Example configuration for Claude Desktop:

```json theme={null}
{
  "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 agents and workflows in your project as MCP tools. You can customize which resources are exposed by adding an `mcp` section to your `config.yml`:

```yaml theme={null}
mcp:
  tools:
    - semantics/topics/*.topic.yml
    - agents/sql-generator.agentic.yml
    - workflows/*.workflow.yml
    - data/*.sql
```

**Supported patterns:**

* Direct file paths: `agents/my-agent.agentic.yml`
* Glob patterns: `agents/*.agentic.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 agents and workflows are exposed by default
* Empty `mcp.tools` list: No tools are exposed

## Resource Types

### Agents

Agents are exposed as MCP tools that answer questions using context from your data.

**Tool naming:** `agent-{agent_name}`

**Input schema:**

```json theme={null}
{
  "question": "string (required)"
}
```

**Example:**

```json theme={null}
{
  "name": "agent-sql-generator",
  "arguments": {
    "question": "Show me total revenue by product category"
  }
}
```

### Workflows

Workflows are exposed as MCP tools with dynamic input schemas based on their variable definitions.

**Tool naming:** `workflow-{workflow_name}`

**Input schema:** Dynamically generated from workflow variables

**Example:**

```json theme={null}
{
  "name": "workflow-monthly-report",
  "arguments": {
    "month": "2024-11",
    "metric": "revenue"
  }
}
```

### SQL Files

SQL files (`.sql`) can be exposed as executable tools.

**Tool naming:** `sql-{filename_without_extension}`

**Input schema:**

```json theme={null}
{
  "database": {
    "type": "string",
    "description": "Database connection to use (optional)"
  }
}
```

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

```sql theme={null}
-- Description: Calculate monthly revenue by product category

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

**Example tool call:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "dimensions": ["string"],
  "measures": ["string"],
  "filters": [{ "field": "string", "operator": "string", "value": "any" }],
  "limit": "number",
  "order_by": [{ "field": "string", "direction": "asc|desc" }],
  "variables": { "type": "object" }
}
```

**Example:**

```json theme={null}
{
  "name": "semantic-sales-analytics",
  "arguments": {
    "dimensions": ["products.category", "time.month"],
    "measures": ["sales.total_revenue", "sales.order_count"],
    "filters": [
      {
        "field": "time.year",
        "operator": "equals",
        "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:**

```json theme={null}
{
  "name": "agent-analytics",
  "arguments": {
    "question": "Show my team's performance"
  },
  "_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:**

```json theme={null}
{
  "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):**

1. Default values from tool definition
2. Variables from tool arguments
3. Variables from `_meta["variables"]`

**Example:**

```json theme={null}
{
  "name": "workflow-report",
  "arguments": {
    "include_tax": false
  },
  "_meta": {
    "variables": {
      "currency": "EUR",
      "organization_id": "org_123"
    }
  }
}
```