OSOP MCP Server: 9 Tools for Any AI Agent

The Model Context Protocol (MCP) is the standardized way for AI agents to use external tools. The OSOP MCP server exposes 9 tools that turn any MCP-compatible agent — GitHub Copilot, Cursor, Claude Desktop — into a workflow-aware system.

Why MCP Matters for OSOP

Without MCP, each AI agent needs a custom integration to use OSOP. With MCP, you install one server and every agent can validate workflows, assess risks, run executions, render diagrams, and more — using the exact same interface.

MCP is to AI tools what USB is to hardware. One protocol, every device.

Installation

pip install osop-mcp
python -m osop_mcp  # starts stdio server

Or with Docker:

docker run -i ghcr.io/archie0125/osop-mcp

The 9 Tools

1. osop.validate

Check a .osop file against the JSON Schema. Returns errors and warnings with line numbers. Use in CI/CD to catch invalid workflows before they run.

2. osop.risk_assess

Analyze a workflow for security risks. Returns a score (0-100) with a verdict (safe/caution/warning/danger) and a list of findings. Checks for missing approval gates, destructive CLI commands, overly broad permissions, hardcoded secrets, unbounded cost exposure, and missing timeouts.

3. osop.run

Execute a workflow with given inputs. Supports dry-run mode for simulation without side effects. Returns execution results with node outputs and final state. Produces a .osoplog on completion.

4. osop.render

Generate a visual diagram from a .osop file. Supports Mermaid, ASCII art, and SVG output. Direction can be top-to-bottom (TB) or left-to-right (LR). The agent can show the user a visual representation of any workflow.

5. osop.test

Run test cases defined in the workflow file. Each test specifies inputs and expected outputs. Returns pass/fail results with details. Use for regression testing of workflow behavior.

6. osop.optimize

Analyze a workflow and suggest improvements. Identifies slow steps, failure hotspots, missing retry policies, parallelization opportunities, and missing error handling. Can return suggestions only or apply them directly.

7. osop.import

Convert external workflow formats to OSOP. Supports GitHub Actions, BPMN, Airflow, Temporal, Postman, and OpenAPI. The agent can import a user's existing workflows into the OSOP format with a single tool call.

8. osop.export

Convert OSOP to external formats. Supports GitHub Actions, BPMN, Airflow, and Temporal. Export your OSOP workflow to a format your CI/CD system already understands.

9. osop.report

Generate a self-contained HTML or text report from a workflow definition and execution log. The HTML report includes node graphs, duration bars, status badges, tool usage, and AI metadata — all in a single file under 15KB.

Configuration

Add to your Claude Desktop config:

// claude_desktop_config.json
{
  "mcpServers": {
    "osop": {
      "command": "python",
      "args": ["-m", "osop_mcp"]
    }
  }
}

Or for Claude Code:

// .mcp.json (in project root)
{
  "mcpServers": {
    "osop": {
      "command": "python",
      "args": ["-m", "osop_mcp"],
      "env": { "OSOP_LOG_LEVEL": "INFO" }
    }
  }
}

What This Enables

With the MCP server installed, your AI agent can:

• Create a workflow from natural language, then validate it immediately
• Import your GitHub Actions workflow and convert it to OSOP
• Run a risk assessment before executing any third-party workflow
• Generate a visual diagram to explain a complex workflow to your team
• Optimize a workflow by analyzing its execution history
• Produce a compliance-ready HTML report after every execution

All through the same interface. No custom integrations needed.

Full API Reference

complete API documentation — See the complete API documentation for all parameters, return types, and configuration options.