Skip to main content

​
Overview

Oxy’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

Oxy 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 --port <port> --project-path <path>

​
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, Oxy 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: 
mcp:
  tools:
    - semantics/topics/*.topic.yml
    - agents/sql-generator.agent.yml
    - workflows/*.workflow.yml
    - data/*.sql
Supported patterns:
  • Direct file paths: agents/my-agent.agent.yml
  • Glob patterns: agents/*.agent.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: 
{
  "question": "string (required)"
}
Example: 
{
  "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: 
{
  "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: 
{
  "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 layer can be exposed as structured query tools. Tool naming: semantic-{topic_name} Input schema: 
{
  "dimensions": ["string"],
  "measures": ["string"],
  "filters": [{"field": "string", "operator": "string", "value": "any"}],
  "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",
        "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: 
{
  "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: 
{
  "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: 
{
  "name": "workflow-report",
  "arguments": {
    "include_tax": false
  },
  "_meta": {
    "variables": {
      "currency": "EUR",
      "organization_id": "org_123"
    }
  }
}