ona-mcp

MCP server for managing Ona AI pipelines from Claude Desktop, Claude Code, and any MCP-compatible client.

Quick Start

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ona": {
      "command": "uvx",
      "args": ["ona-mcp"],
      "env": {
        "ONA_API_KEY": "your-org-api-key"
      }
    }
  }
}

Claude Code

claude mcp add ona -- uvx ona-mcp

Then set ONA_API_KEY in the MCP config, or add it manually:

{
  "mcpServers": {
    "ona": {
      "command": "uvx",
      "args": ["ona-mcp"],
      "env": {
        "ONA_API_KEY": "your-org-api-key"
      }
    }
  }
}

Manual install

pip install ona-mcp

Configuration

Available Tools

Pipeline Management

• list_pipelines - List all pipelines with deployment status
• get_pipeline - Get pipeline details and modules
• create_pipeline - Create a new pipeline from a template
• update_pipeline - Update pipeline name or description
• delete_pipeline - Delete a pipeline

Code / Modules

• get_package_structure - View the file tree
• list_modules - List all modules in a package
• read_module - Read module source code
• write_module - Create or update a module (upsert)
• delete_module - Delete a module

Versioning

• deploy_pipeline - Deploy draft to production
• rollback_pipeline - Rollback to a previous version
• list_versions - View version history

Testing & Quality

• test_pipeline - Test a pipeline with a message; pass tool_mocks={"get_contact_context": [{"returns": {...}}]} to run it with the platform contact briefing production injects (AB-340)
• run_evaluations - Run evaluation suites
• get_quality_history - View evaluation score history

Triggers

• list_triggers - List all triggers (schedules, events, channels)
• create_schedule - Create a cron schedule trigger
• delete_schedule - Delete a schedule trigger
• run_trigger_now - Manually fire a trigger

Executions

• list_executions - View execution history
• get_execution - Get execution details and logs
• cancel_execution - Cancel a running execution

Security

• API key is read from environment variables only (never passed as CLI arguments)
• All requests are authenticated via the Ona backend's auth middleware
• Data is scoped to your organization by the API key
• No database credentials or internal state are exposed
• A warning is shown if ONA_BASE_URL uses HTTP for non-localhost targets

Development

cd ona-mcp
pip install -e ".[dev]"
pytest tests/ -v