opsorch-mcp

OpsOrch/opsorch-mcp

3.3

If you are the rightful owner of opsorch-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

OpsOrch-MCP is a Model Context Protocol server that interfaces with OpsOrch Core HTTP APIs, providing a secure and efficient way to manage operations through LLM and agent runtimes.

Tools
18
Resources
0
Prompts
0

opsorch-mcp

Version License CI

opsorch-mcp is the Model Context Protocol (MCP) server for OpsOrch. It exposes OpsOrch Core HTTP APIs as safe, read-only MCP tools for LLM and agent runtimes.

Getting started

Local Development

npm install
npm run dev    # runs via ts-node over stdio
# or
npm run build && npm start

The server uses stdio transport by default; spawn it from your MCP client (e.g., Claude Code, MCP Inspector, Cursor) pointing to the compiled dist/index.js.

Docker

Docker images are automatically built and published to GitHub Container Registry with each release. You can run the MCP server using Docker:

# Pull the latest version
docker pull ghcr.io/opsorch/opsorch-mcp:latest

# Run with environment variables
docker run -d \
  --name opsorch-mcp \
  -p 7070:7070 \
  -e OPSORCH_CORE_URL=http://localhost:8080 \
  -e OPSORCH_CORE_TOKEN=changeme \
  -e MCP_HTTP_PORT=7070 \
  ghcr.io/opsorch/opsorch-mcp:latest

# Or run a specific version
docker pull ghcr.io/opsorch/opsorch-mcp:v1.0.0

# Using Docker Compose
cat > docker-compose.yml << EOF
version: '3.8'
services:
  opsorch-mcp:
    image: ghcr.io/opsorch/opsorch-mcp:latest
    ports:
      - "7070:7070"
    environment:
      - OPSORCH_CORE_URL=http://localhost:8080
      - OPSORCH_CORE_TOKEN=changeme
      - OPSORCH_LOG_LEVEL=info
      - MCP_HTTP_PORT=7070
    restart: unless-stopped
EOF

docker-compose up -d

Available Docker tags:

  • latest - Latest stable release
  • v{version} - Specific version tags (e.g., v1.0.0, v1.1.0)

The Docker image runs as a non-root user and exposes port 7070 by default (configurable via MCP_HTTP_PORT environment variable). The image supports both stdio and HTTP transports for MCP communication.

Configure where to reach OpsOrch Core:

OPSORCH_CORE_URL=http://localhost:8080 \
OPSORCH_CORE_TOKEN=changeme            # Bearer token (default 'demo' if unset)
OPSORCH_CORE_TIMEOUT_MS=15000           # optional
OPSORCH_LOG_LEVEL=debug                 # optional (debug, info, warn, error)
MCP_HTTP_PORT=7070                      # optional HTTP transport (set 0 to disable)
MCP_HTTP_ALLOW_ORIGINS=https://app.local # optional CORS allow-list (comma-separated)
MCP_HTTP_ALLOW_HOSTS=app.local          # optional host header allow-list (comma-separated)
npm run dev

Transports

The server always binds a stdio transport for MCP-native clients. By default it also exposes an HTTP endpoint on http://localhost:7070/mcp so you can run stateless JSON-RPC calls (see curl examples below). Set MCP_HTTP_PORT=0 to skip HTTP entirely or change it to another positive integer to listen elsewhere. When serving remote clients, configure MCP_HTTP_ALLOW_ORIGINS (CORS) and MCP_HTTP_ALLOW_HOSTS (Host header allow-list) with comma-separated values.

Quick HTTP MCP checks (curl)

HTTP transport here runs stateless: you can issue a single POST per call (no session or initialize required). Include the Accept header:

# list tools
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# query incidents
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query-incidents","arguments":{"query":"error","limit":5}}}'

# query tickets
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"query-tickets","arguments":{"query":"outage","limit":5}}}'

# query deployments
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"query-deployments","arguments":{"statuses":["success"],"environments":["production"],"limit":10}}}'

# get deployment
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"get-deployment","arguments":{"id":"deploy-123"}}}'

# query teams
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"query-teams","arguments":{"name":"velocity","limit":5}}}'

# get team
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"get-team","arguments":{"id":"team-velocity"}}}'

# get team members
curl -s http://localhost:7070/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"get-team-members","arguments":{"id":"team-velocity"}}}'

Tools (OpsOrch Core)

This server currently exposes read-only tools for querying and retrieving data. No mutation tools are available.

  • query-incidents – POST /incidents/query
  • get-incident – GET /incidents/{id}
  • get-incident-timeline – GET /incidents/{id}/timeline
  • query-alerts – POST /alerts/query
  • query-logs – POST /logs/query
  • query-metrics – POST /metrics/query
  • describe-metrics – POST /metrics/describe
  • query-tickets – POST /tickets/query
  • get-ticket – GET /tickets/{id}
  • query-deployments – POST /deployments/query
  • get-deployment – GET /deployments/{id}
  • query-services – POST /services/query
  • query-teams – POST /teams/query
  • get-team – GET /teams/{id}
  • get-team-members – GET /teams/{id}/members
  • query-orchestration-plans – POST /orchestration/plans/query
  • get-orchestration-plan – GET /orchestration/plans/{id}
  • list-providers – GET /providers/{capability} where capability is one of incident, alert, log, metric, ticket, service, deployment, team, or orchestration

Logging

  • OPSORCH_LOG_LEVEL controls verbosity (debug, info, warn, error).
  • Every OpsOrch Core HTTP call logs method, path, duration, and status.
  • debug adds request/response payloads so you can trace agent decisions end-to-end.

Tool input field types

Documented below so agents can quickly see whether a field should be a string, integer, or structured payload and which ranges apply.

  • Query/list limits: every limit argument is an optional positive integer (> 0). Keep requested rows lean (tens, not hundreds) unless a human explicitly approves a broader fetch.
  • Scope: scope.service, scope.team, and scope.environment are optional strings that narrow every query and should always be set when known.
  • Incident queries (query-incidents): query is a free-text string; statuses/severities are string arrays; metadata is an object with provider-specific keys.
  • Alert queries (query-alerts): query is a free-text string; statuses/severities are string arrays.
  • Log queries (query-logs): start/end are ISO-8601 timestamps; limit is the max number of entries; providers is an optional string array so you can force a connector. Always bound the time range before asking for approval on costly scans.
  • Metric queries (query-metrics): expression is the provider-native query string; step is a duration string accepted by the provider (e.g., 30s, 5m). Timestamps follow ISO-8601.
  • Describe metrics (describe-metrics): scope is the standard query scope.
  • Service queries (query-services): ids is an optional string array; tags is a map of string key/value filters.
  • Team queries (query-teams): name is an optional string for name-based filtering; tags is a map of string key/value filters for team attributes.
  • Ticket queries (query-tickets): query is a free-text string; statuses/assignees are string arrays.
  • Deployment queries (query-deployments): query is a free-text string; statuses/environments are string arrays; supports standard scope filtering for targeted deployment searches.

Resources

  • opsorch://docs/agents-architecture – serves AGENTS.md so clients can retrieve the OpsOrch Agents Architecture content directly.

Project scripts

  • npm run dev – run TypeScript entrypoint with ts-node.
  • npm run build – emit compiled JS to dist/.
  • npm start – run the compiled server from dist/.

Fill in AGENTS.md as needed; all tools already target the OpsOrch Core HTTP API surfaces.

Releases

This project uses automated releases via GitHub Actions. Releases are triggered manually and include:

  • Semantic versioning with configurable version bumps (major, minor, patch)
  • Automated testing and linting before release
  • Git tagging with proper version format (v{major}.{minor}.{patch})
  • Changelog generation from commit history
  • Docker image publishing to GitHub Container Registry
  • GitHub releases with release notes

Creating a Release

Maintainers can create a new release by:

  1. Go to the Actions tab
  2. Select the "Release" workflow
  3. Click "Run workflow"
  4. Choose the version bump type:
    • patch - Bug fixes and minor updates (1.0.0 → 1.0.1)
    • minor - New features, backward compatible (1.0.0 → 1.1.0)
    • major - Breaking changes (1.0.0 → 2.0.0)
  5. Click "Run workflow"

The release process will automatically:

  • Run all tests and linting
  • Calculate the next version number
  • Create and push a git tag
  • Build and publish Docker images for multiple architectures (linux/amd64, linux/arm64)
  • Create a GitHub release with changelog

Installation Options

Docker:

docker pull ghcr.io/opsorch/opsorch-mcp:latest

GitHub Releases: Download release artifacts from the Releases page.