Skip to main content
Glama

SuperOps.ai MCP Server

MCP server for Claude that provides tools to interact with the SuperOps.ai PSA/RMM platform using their GraphQL API.

One-Click Deployment

Deploy to DO

Deploy to Cloudflare Workers

Operator note — GitHub Packages authentication. This package is published to the @wyre-ai scope on GitHub Packages, which requires an authentication token on every install (GitHub Packages has no anonymous reads, even for public packages). Create a GitHub Personal Access Token with the read:packages scope and supply it to the cloud builder:

  • Cloudflare Workers — set a build variable named NODE_AUTH_TOKEN to your PAT.

  • DigitalOcean App Platform — set a build-time secret named GITHUB_TOKEN to your PAT.

For local installs, run export NODE_AUTH_TOKEN=$(gh auth token) before npm install.

Related MCP server: ninjaone-mcp

Features

  • Decision Tree Architecture: Navigate to domains (clients, tickets, assets, technicians) to see relevant tools

  • Lazy Loading: Domain modules load on-demand for faster startup

  • Full CRUD Operations: List, get, create, and update entities

  • GraphQL Support: Use custom queries for advanced operations

  • Interactive Ticket Card (MCP Apps): ticket results render as an interactive card in MCP Apps hosts — neutral by default, brandable via window.__BRAND__ injection or MCP_BRAND_* env vars

Interactive Ticket Card (MCP Apps)

superops_tickets_get renders as an interactive card in MCP Apps hosts (Claude Desktop/web) with an in-card "Add note" round-trip via superops_tickets_add_note that always posts internal-only notes (isPublic: false); plain-JSON behavior is unchanged in other hosts. The card is neutral by default and brandable via window.__BRAND__ injection or MCP_BRAND_* env vars (MCP_BRAND_NAME, MCP_BRAND_LOGO_URL, MCP_BRAND_PRIMARY_COLOR, MCP_BRAND_ACCENT_COLOR, MCP_BRAND_BG, MCP_BRAND_TEXT) — no rebuild needed.

Installation

# The @wyre-ai scope lives on GitHub Packages and needs a token to install:
export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/superops-mcp

Configuration

Copy .env.example and set the variables below. Leave CONDUIT_S2S_SECRET empty in that example; generate a real value with openssl rand -hex 32 and do not commit it.

export SUPEROPS_API_TOKEN="your-api-token"
export SUPEROPS_SUBDOMAIN="yourcompany"
export SUPEROPS_REGION="us"  # or "eu" for EU region

Variable

Required

Description

SUPEROPS_API_TOKEN

For stdio and AUTH_MODE=env

SuperOps.ai API token

SUPEROPS_SUBDOMAIN

For stdio and AUTH_MODE=env

SuperOps.ai subdomain

SUPEROPS_REGION

No

us (default) or eu

MCP_TRANSPORT

No

stdio (default) or http

AUTH_MODE

No

env (default outside Docker) or gateway. The image and Compose default to gateway. Gateway mode requires X-SuperOps-API-Token and X-SuperOps-Subdomain on each /mcp request and never falls back to SUPEROPS_*.

CONDUIT_S2S_SECRET

Yes for HTTP

HMAC secret for X-Gateway-S2S. Empty values and known placeholders (replace-with-a-real-secret, your-s2s-secret, changeme, and similar) log an error and exit non-zero. Compose will not start when it is unset. The value is never logged.

MCP_ALLOW_INSECURE_DEV

No

Set to 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. Logs a warning, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. A non-loopback MCP_HTTP_HOST refuses to start. A known placeholder secret is refused even when this flag is set.

MCP_HTTP_HOST

No

Bind address when a real CONDUIT_S2S_SECRET is set. Defaults to 127.0.0.1. The container image sets 0.0.0.0.

MCP_HTTP_PORT

No

HTTP port. Defaults to 8080.

/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http, every /mcp request must include X-Gateway-S2S once CONDUIT_S2S_SECRET is set. The header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read.

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In AUTH_MODE=gateway, add X-SuperOps-API-Token and X-SuperOps-Subdomain as well. Missing credential headers are HTTP 401 and do not fall back to SUPEROPS_* in the environment. With AUTH_MODE=env, the signed request uses those variables from the process environment.

Standalone local use that cannot sign requests:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Startup logs a warning, skips the S2S check, and binds 127.0.0.1 only. Do not publish that port off loopback.

Getting Your API Token

  1. Log in to SuperOps.ai

  2. Click settings icon > "My Profile"

  3. Navigate to "API token" tab

  4. Click "Generate token"

  5. Copy and securely store the token

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "superops": {
      "command": "npx",
      "args": ["@wyre-ai/superops-mcp"],
      "env": {
        "SUPEROPS_API_TOKEN": "your-api-token",
        "SUPEROPS_SUBDOMAIN": "yourcompany",
        "SUPEROPS_REGION": "us"
      }
    }
  }
}

Available Domains & Tools

Navigation

  • superops_navigate - Navigate to a domain

  • superops_back - Return to main menu

  • superops_test_connection - Test API connectivity

Clients Domain

  • superops_clients_list - List clients with filters

  • superops_clients_get - Get client details

  • superops_clients_search - Search clients by name

Tickets Domain

  • superops_tickets_list - List tickets with filters

  • superops_tickets_get - Get ticket details

  • superops_tickets_create - Create a new ticket

  • superops_tickets_update - Update ticket status/assignment

  • superops_tickets_add_note - Add note to ticket

  • superops_tickets_log_time - Log time on ticket

Assets Domain

  • superops_assets_list - List assets/endpoints

  • superops_assets_get - Get asset details

  • superops_assets_software - Get software inventory

  • superops_assets_patches - Get patch status

Technicians Domain

  • superops_technicians_list - List technicians

  • superops_technicians_get - Get technician details

  • superops_technicians_groups - List technician groups

Custom Domain

  • superops_custom_query - Run custom GraphQL query

  • superops_custom_mutation - Run custom GraphQL mutation

Example Usage

User: What tools are available?
Claude: Use superops_navigate to select a domain...

User: Navigate to tickets
Claude: [calls superops_navigate with domain: "tickets"]
Now in tickets domain. Available tools: superops_tickets_list, superops_tickets_get...

User: Show open high priority tickets
Claude: [calls superops_tickets_list with status: ["Open"], priority: ["High"]]
Here are the open high priority tickets...

Docker

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST), defaults to AUTH_MODE=gateway, and refuses to start unless CONDUIT_S2S_SECRET is a real secret. Publish the port on loopback. In gateway mode, SuperOps credentials arrive on each request as headers; they are not read from the environment.

docker build -t superops-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  superops-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not pass SUPEROPS_API_TOKEN or SUPEROPS_SUBDOMAIN into the container:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Sign /mcp the same way as in HTTP authentication. A gateway-mode call also sends the vendor headers:

curl -sS http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-SuperOps-API-Token: $SUPEROPS_API_TOKEN" \
  -H "X-SuperOps-Subdomain: $SUPEROPS_SUBDOMAIN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses SUPEROPS_API_TOKEN and SUPEROPS_SUBDOMAIN. The DigitalOcean one-click template is that mode: set CONDUIT_S2S_SECRET as a runtime secret.

Rate Limits

SuperOps.ai API has a rate limit of 800 requests per minute per API token.

Pagination

SuperOps uses page-based pagination, not cursors. List tools take page (1-indexed, default 1) and pageSize (default 50, max 100), and return a listInfo block with page, pageSize, totalCount and hasMore.

hasMore is tri-state: true when another page exists, null — never false — when it does not. Loop on hasMore === true, or page off totalCount; looping until hasMore === false never terminates.

Filtering

Filters are condition clauses of { attribute, operator, value }, and they compose — { joinOperator: "and" | "or", operands: [ … ] } nests recursively. Operators verified against a live tenant:

Operator

Value

is, isNot, contains, notContains, startsWith, endsWith

string

includes, notIncludes

array

equals and in are rejected by the API. includes matches a value whole while contains matches a substring — filtering an OS platform with includes: ["Windows"] matches nothing, because SuperOps stores "Microsoft Windows 10 Pro".

Two things to know, because neither reports an error:

  • Filtering on a value outside a field's real set returns zero rows, not an error. An empty result may mean a bad value, not an empty tenant.

  • Filtering on a JSON column (software) rather than a path into it (software.name) also returns zero rows silently.

Use superops_custom_query for filter semantics the standard tools don't express.

Schema conformance

schema/superops.graphql is a vendored copy of the SuperOps GraphQL schema:

# Authoritative — generated from live introspection
SUPEROPS_API_TOKEN=... SUPEROPS_SUBDOMAIN=... node scripts/fetch-schema.mjs

# No credentials? Falls back to scraping the published API reference
node scripts/fetch-schema.mjs

Prefer introspection, and note the committed schema is already the introspected one. The published docs declare 276 types / 76 queries / 63 mutations where the live API reports 404 / 116 / 83, omit deprecations entirely, and declare two types that do not exist live (FieldType, TicketType) — validating against those would pass documents the API rejects.

src/domains/graphql-schema.test.ts validates every GraphQL document in src/ against it on each npm test, so a query referencing a field SuperOps does not define fails in CI rather than at runtime. Regenerate the schema after a SuperOps API change and re-run the tests.

License

Apache-2.0

Support

For issues and feature requests, please visit the GitHub repository.

Available Tools

22 tools
superops_assets_getA

Get detailed information for a specific asset: hardware identity (manufacturer, model, serial number), platform and OS version, network details (public IP, primary MAC, gateway, domain), agent version and patch status. SuperOps does not expose CPU, memory or disk figures on the asset record — use superops_custom_query with getAssetSummary or getAssetDiskDetails for those.

Inputs: assetId (required).

superops_assets_listA

List assets (endpoints) in SuperOps.ai RMM. Supply any combination of status, platform and clientId; several filters are combined with AND. listInfo.hasMore is true when a further page exists and null (never false) when it does not, so treat null as the end or page against totalCount.

Inputs: page, status, clientId, pageSize, +1 more.

superops_assets_patchesA

Get patch status and patch details for a specific asset: title, KB numbers, category, severity, approval status and installation status. installationStatus and severity may be combined; they are joined with AND. For a one-word roll-up of the asset's overall patch health instead of the per-patch list, use superops_custom_query with getAssetPatchStatus.

Inputs: assetId (required), page, pageSize, severity, +1 more.

superops_assets_softwareB

Get the software inventory for a specific asset: name, version, install date, bit version and install path.

Inputs: assetId (required), page, search, pageSize.

superops_clients_getA

Get detailed information for a specific client by their account ID.

Inputs: accountId (required).

superops_clients_listB

List clients (accounts) in SuperOps.ai. Results are paginated with page/pageSize. Supplying both stage and status narrows to clients matching both.

Inputs: page, stage, status, pageSize.

superops_custom_mutationB

Run a custom GraphQL mutation against the SuperOps.ai API. For advanced write operations not covered by standard tools.

Inputs: mutation (required), variables.

superops_custom_queryA

Run a custom GraphQL query against the SuperOps.ai API. For advanced use cases not covered by standard tools.

Inputs: query (required), variables.

superops_navigateA

Discover available SuperOps.ai tools by domain. Returns tool names and descriptions for the selected domain. All tools are callable at any time — this is a help/discovery aid, not a prerequisite.

Inputs: domain (required).

superops_statusB

Show credentials status and available domains

Inputs: no named parameters.

superops_technicians_getA

Get detailed information for a specific technician by their user ID. SuperOps has no single-technician endpoint, so this filters the technician list to that ID. Returns the technician's contact details plus their role as {roleId, name} and their group roster as an array of {groupId, name}; designation, businessFunction, team and reportingManager are null unless the tenant assigns them. Skills, ticket counts and response-time metrics are not available from SuperOps.

Inputs: technicianId (required).

superops_technicians_groupsA

List technician groups/teams in SuperOps.ai. Returns every group's ID and name — SuperOps exposes no description, member count or member roster for a group, and the endpoint is neither paginated nor filterable. These are the same groups that appear in a technician's groups field, so a group ID from here identifies the group a technician belongs to.

Inputs: no named parameters.

superops_technicians_listA

List technicians (agents) in SuperOps.ai, sorted by name. Optionally narrow the list with a search term, matched as a substring against both name and email. SuperOps does not expose an active/inactive flag, ticket counts or last-login times for technicians. Each technician's role comes back as {roleId, name} and their groups as an array of {groupId, name}; designation, businessFunction, team and reportingManager are null unless the tenant assigns them. listInfo.hasMore is true when a further page exists and null when it is not — it is never false, so page against totalCount. Use superops_custom_query for filters beyond a name search.

Inputs: page, search, pageSize.

superops_technicians_lookupsA

List the roles, teams, designations, business functions and technician groups defined in this SuperOps tenant, each as {id, name}. These are the values a technician's role, team, designation, businessFunction and groups fields refer to. Use this to turn a name a user gave you ("the Sales team", "Admin role") into the ID SuperOps filters on, then pass that ID to superops_custom_query — getTechnicianList accepts a condition on the role and groups attributes. Takes no arguments.

Inputs: no named parameters.

superops_test_connectionA

Test the connection to SuperOps.ai API using configured credentials.

Inputs: no named parameters.

superops_tickets_add_noteA

Add a note to a ticket. Can be internal or public (visible to client).

Inputs: content (required), ticketId (required), isPublic.

superops_tickets_createB

Create a new ticket in SuperOps.ai. Status, priority, category and subcategory are free-text strings that must match the values configured in your SuperOps tenant.

Inputs: subject (required), clientId (required), impact, siteId, +11 more.

superops_tickets_getA

Get detailed information for a specific ticket by its ID.

Inputs: ticketId (required).

superops_tickets_listA

List tickets in SuperOps.ai. Results are paginated with page/pageSize. All supplied filters are combined: a ticket must match every one of status, priority, clientId and technicianId that you provide, and within status and priority it may match any of the listed values.

Inputs: page, status, clientId, pageSize, +2 more.

superops_tickets_log_timeB

Log a worklog entry against a ticket. SuperOps records quantity (not a raw minute count) against the service item's unit — typically hours.

Inputs: qty (required), ticketId (required), notes, billable, +5 more.

superops_tickets_updateA

Update an existing ticket - change status, priority, assignment, or category. Free-text resolution notes belong in superops_tickets_add_note; only the tenant's configured resolutionCode can be set here.

Inputs: ticketId (required), impact, status, subject, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools target a clearly distinct resource+action (clients_list/get/search, tickets_list/get/create/update, assets_*), and descriptions clarify boundaries well. The only mild overlap is superops_technicians_groups vs superops_technicians_lookups, since both expose group data, but the descriptions explicitly distinguish a group roster from a lookup of role/team/group IDs.

    Naming Consistency4/5

    Strong, predictable pattern of superops_<entity>_<action> (clients_list, tickets_create, assets_get, technicians_groups) in consistent snake_case. A few utility tools (status, test_connection, custom_query, custom_mutation, navigate) drop the entity segment, but they remain snake_case and readable.

    Tool Count4/5

    22 tools is on the heavier side, but they span four distinct domains (clients, tickets, assets, technicians), so roughly 5 per resource family is well-scoped. Each tool serves a genuine operation, and the escape-hatch tools (custom_query/mutation) reduce the need for more granular endpoints.

    Completeness4/5

    Tickets have full lifecycle coverage (list, get, create, update, add_note, log_time); assets cover identity, software and patches; technicians cover list/get/groups/lookups. Clients are read-only (no create/update) and there is no ticket delete, but custom_query/custom_mutation provide a workaround for the gaps.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server for the NinjaOne RMM platform, enabling tools to manage devices, organizations, alerts, jobs, and policies through NinjaOne's API.
      32
      Apache 2.0
    • A
      license
      B
      quality
      A
      maintenance
      An MCP server for CIPP (Community IT Professionals Platform), enabling MSPs to manage Microsoft 365 tenants, users, policies, and security settings through CIPP's API.
      49
      13
      Apache 2.0