Model Context Protocol (MCP) Server

OmniRoles MCP Server

Connect OmniRoles directly to your AI development workflows. Give your local coding agent — Cursor, Windsurf, Claude Code, Antigravity, Hermes, OpenCode — direct read/write access to OmniRoles project backlogs, story details, and real-time execution status tracking.

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open standard developed by Anthropic for securely connecting AI models and applications to tools and data sources. OmniRoles provides a dedicated MCP server package: omniroles-mcp-server.

Learn more at modelcontextprotocol.io →

Exposed Developer Tools

1. omniroles_list_projectsDiscovery Tool

Lists all active projects and workflows belonging to the user's active workspace tenant.

Arguments: skip (int, optional, default 0), limit (int, optional, default 50)

2. omniroles_get_project_backlogHierarchy Tool

Reconstructs the complete sprint, user story, subtask, and API contract hierarchy for a targeted project ID.

Arguments: project_id (int, required)

3. omniroles_get_story_detailsSpecification Tool

Retrieves deep functional specs, acceptance checklists, and exact API schemas for a targeted User Story ID.

Arguments: project_id (int, required), story_id (string, required — e.g. "STORY-AUTH-001")

4. omniroles_update_agent_progressReal-Time Sync

Broadcasts real-time execution states (todo / in_progress / done / failed) and checklist items directly to the OmniRoles dashboard.

Arguments: project_id (int), story_id (str), status (str), comments (str), backend_tasks_completed (array), frontend_tasks_completed (array)

Installation & Environment Setup

Install via uv (Recommended)

uv add omniroles-mcp-server

Environment Variables

Variable	Required	Description
OMNIROLES_BASE_URL	Yes	API endpoint (default: https://api.omniroles.com/v1)
OMNIROLES_API_KEY	Yes	Persistent workspace API token
OMNIROLES_TENANT_ID	No	Workspace tenant ID (auto-detected if omitted)

Session Cache Auto-Detection: In dispatched execution environments, the launcher automatically injects a local session cache file (.dispatch_session.json), allowing the MCP server to connect automatically without manual credential flags.

Client IDE & Agent Setup Guides

1. Cursor IDE Setup

Open Cursor Settings (Gear icon → Features → MCP).
Click + Add New MCP Server.
Set Name: omniroles-mcp, Type: command.
Command: uv run omniroles-mcp-server

2. Windsurf IDE Setup

Add the server configuration to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "omniroles-mcp": {
      "command": "uv",
      "args": ["run", "omniroles-mcp-server"],
      "env": {
        "OMNIROLES_BASE_URL": "https://api.omniroles.com/v1",
        "OMNIROLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Claude Desktop App Setup

Add to your Claude configuration file (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "omniroles-mcp": {
      "command": "uv",
      "args": ["run", "omniroles-mcp-server"],
      "env": {
        "OMNIROLES_BASE_URL": "https://api.omniroles.com/v1",
        "OMNIROLES_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Claude Code CLI Setup

claude mcp add omniroles-mcp uv -- run omniroles-mcp-server

5. Antigravity, Hermes & Custom CLI Agents

For agentic platforms like Antigravity, Hermes, or OpenCode, register the standard subprocess launcher command. The runtime will automatically receive typed tool schemas, query tasks, and update milestones as code edits compile cleanly.

Typical Developer Agent Workflow

Step 1:Agent calls omniroles_list_projects() to discover active user story assignments.

Step 2:Agent calls omniroles_get_project_backlog(project_id=25) to pull PRD specs, acceptance criteria, and API endpoints.

Step 3:Agent updates status to in_progress via omniroles_update_agent_progress(), broadcasting real-time state to the web UI.

Step 4:Agent writes code, passes unit tests, and transitions story state to done.

Direct SaaS Compute Consumption

OmniRoles MCP Server provides access solely to BrandXpoint's proprietary software engine. Each MCP tool call consumes credit units from your direct subscription. No marketplace fee structure or third-party vendor access.