ReliaQuest GreyMatter MCP Server

A Model Context Protocol server that exposes the ReliaQuest GreyMatter Self-Service GraphQL API to AI assistants. It provides 146 tools across 22 domains — Incidents, Tasks, Detections, Playbooks, Cases, DRP Alerts, Assets, Identities, Reference Lists, Users, and more — plus a generic graphql_query escape hatch for anything not covered by a dedicated tool. The tool set is generated directly from the vendor's API collection, so it stays faithful to the real API surface, and it has been verified against the live GraphQL schema.

Tools

146 tools across 22 domains (56 queries + 90 mutations), plus the graphql_query escape hatch. In read-only mode only the 56 queries (and a query-only graphql_query) are registered.

146 tools total. Highlights:

• List queries (incidents, tasks, assets, detection_rules, cases, …) are Relay-paginated — pass first/after and read edges, pageInfo, and totalCount. Most accept a domain filter and order input (e.g. incidentFilter, incidentOrder).

• Single-item queries (incident, task, case, user, …) take a by argument (e.g. an id or ticket number) to fetch one record with its full detail and comments.

• Incident workflow mutations cover the GreyMatter Investigate lifecycle: acknowledge_incident, assign_incident, add_incident_comment, update_incident_state, and close_incident. Incident close codes include CUSTOMER_TRUE_POSITIVE, CUSTOMER_FALSE_POSITIVE, CUSTOMER_ANOMALOUS_SAFE, FALSE_POSITIVE_CREATE_TUNING_TICKET, CUSTOMER_SECURITY_CONTROL_TESTING, CUSTOMER_CANCELLED; states include PENDING_CUSTOMER, PENDING_RQ, RESOLVED, CANCELLED.

• Respond / playbooks: run_playbook executes a predefined playbook; playbook_runs and playbook_run read execution results.

• graphql_query escape hatch runs an arbitrary GraphQL document for anything without a dedicated tool. In read-only mode it rejects mutations.

• customer_slug on every tool overrides the x-reliaquest-customer (OpCo) header for that single call — see Multi-OpCo.

• rate_limit reports your remaining API budget (the API allows 5000 points/hour per company account; each returned node counts as one point).

See docs/ENDPOINTS.md for the full tool ↔ GraphQL-operation mapping.

Quick start

Install

# with uv (recommended)
uv tool install greymatter-mcp

# or with pip
pip install greymatter-mcp

For development from source:

git clone https://github.com/Space-C0wboy/Reliaquest-Greymatter-MCP-Server
cd Reliaquest-Greymatter-MCP-Server
uv venv && uv pip install -e ".[dev]"

Getting an API key

Generate a GreyMatter API key from the portal:

1. In GreyMatter, go to Settings → API Key Management.

2. Click New API Key, choose an Expiration Date (default is 1 year), then Create Key.

3. Copy the key — it is shown only once. This is your GREYMATTER_API_KEY.

Configuration

Copy .env.example to .env and set:

Run

• stdio (default): uv run greymatter-mcp (or just greymatter-mcp if installed as a tool)

• HTTP: greymatter-mcp --transport http --port 8765

Read-only mode

Set GREYMATTER_READ_ONLY=true to run the server safely against production. In this mode:

• No mutation tools are registered — only the 56 query tools are exposed.

• The graphql_query escape hatch rejects mutations, so it can only run read operations (robust against fragment- or BOM-prefixed mutation documents).

Read-only mode is strongly recommended for analyst-assistant, dashboard, and reporting use cases where the model should never be able to change state.

Editor integration

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "greymatter": {
      "command": "greymatter-mcp",
      "env": {
        "GREYMATTER_API_KEY": "your-key-here",
        "GREYMATTER_READ_ONLY": "true"
      }
    }
  }
}

If running from source instead of an installed tool, use uv with --directory:

{
  "mcpServers": {
    "greymatter": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/Reliaquest-Greymatter-MCP-Server", "greymatter-mcp"],
      "env": { "GREYMATTER_API_KEY": "your-key-here", "GREYMATTER_READ_ONLY": "true" }
    }
  }
}

Restart Claude Desktop, then confirm greymatter appears in the tools menu.

Claude Code

claude mcp add greymatter \
  --env GREYMATTER_API_KEY=your-key-here \
  --env GREYMATTER_READ_ONLY=true \
  -- greymatter-mcp

Multi-OpCo (Header Slug)

GreyMatter accounts that manage multiple operating companies (OpCos) use the x-reliaquest-customer header ("Header Slug") to select which company a request targets:

• Set GREYMATTER_CUSTOMER_SLUG to apply a default slug to every request.

• Pass customer_slug on any individual tool call to override the default for that call. Both set the x-reliaquest-customer header.

Rate limits

The GreyMatter API enforces a limit of 5000 points/hour per company account. Each node entity returned counts as 1 point, so large paginated queries consume points quickly. Use the rate_limit tool to check your current usage.

Known limitations

The tools mirror the vendor's API collection. A few operations are affected by server-side issues in the GreyMatter API itself (not by this server), observed during live testing. They are documented here and reported to ReliaQuest (docs/reliaquest-api-issues.md):

• cases / case — the underlying query errors at node.discoverExposure for accounts not entitled to the Discover/exposure capability (the resolver raises instead of returning null, failing the whole query). Workaround (built in): this server omits the discoverExposure field, so the tools work out of the box. Request that field via graphql_query if you need it.

• playbooks — the underlying query fails to serialize its own enum (TechnologyType value MOBILE_DEVICE_MANAGEMENT) under supportedTechnologies.type. Workaround (built in): this server omits the supportedTechnologies field, so the tool works. Request that field via graphql_query if you need it.

• greymatter_fields and the single-item drp_alert can return "An unexpected error has occurred" depending on account entitlement.

Entitlement-gated tools. Some tools return "You don't have access to this item" unless your account/API key is licensed for the relevant module — e.g. drp_alerts, access_control_policies, access_control_resources, discover_tasks, audits. These work normally for entitled accounts.

Multi-connection queries. A few queries page several nested connections and expose multiple first / after parameters (e.g. cases uses first3/after3 for the top-level list and first/first1/first2 for nested connections). Always set the outer page-size parameter to bound results; leaving it unset can return very large responses and time out. For heavy queries (e.g. playbook_run_filter_data), raise GREYMATTER_TIMEOUT.

Example prompts

• "Show me incidents pending customer action." → incidents (filter on state: PENDING_CUSTOMER).

• "Acknowledge incident <id> and assign it to me." → acknowledge_incident → assign_incident.

• "Resolve incident <id> as a false positive with a tuning note." → close_incident (closeCode: CUSTOMER_FALSE_POSITIVE).

• "What detection rules are deployed, and which map to MITRE techniques?" → detection_rules.

• "List the 25 most recent open cases." → cases (set first3: 25).

• "How much of my API rate-limit budget is left?" → rate_limit.

How tools are generated

The tools are generated from the vendor's API collection:

python scripts/generate_from_collection.py

This regenerates the modules under src/greymatter_mcp/tools/_generated/ and the catalog at docs/ENDPOINTS.md. The generated files are not hand-edited — change the generator (its OVERRIDES / FIELD_EXCLUSIONS maps) and regenerate.

The API collection and other ReliaQuest reference material live in the Development Reference/ directory, which is gitignored: it is ReliaQuest proprietary material and is not redistributed in this public repository. To verify the generated tools against the live API, scripts/introspect.py fetches the current GraphQL schema.

Development

uv run pytest        # full suite (HTTP fully mocked; no live calls)
uv run ruff check .  # lint
uv run python scripts/generate_from_collection.py  # regenerate tools

Releases publish to PyPI when a v* tag is pushed (see .github/workflows/release.yml).

License

MIT

Support

This is an unofficial community project. For GreyMatter platform or API questions, contact ReliaQuest at greymattersupport@reliaquest.com. For issues with this MCP server, open an issue on the GitHub repository.