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.

[!IMPORTANT] Unofficial project. This is an independent, community-built MCP server developed against ReliaQuest's published API documentation. It is not an official ReliaQuest product and is not affiliated with, endorsed by, or supported by ReliaQuest, LLC. "ReliaQuest" and "GreyMatter" are trademarks of ReliaQuest, LLC. For official support of the GreyMatter platform or the API itself, contact ReliaQuest directly at greymattersupport@reliaquest.com.

[!WARNING] Beta software — not yet recommended for production environments. This project is under active development. The tool surface and individual tool body shapes may still change between minor versions, and not every endpoint has been exhaustively exercised against every account/entitlement configuration. Use against a non-production scope until you're confident in the behavior for your use case.

This server can perform destructive actions against your GreyMatter environment. Tools can close and cancel incidents/cases/tasks, run response playbooks, and create or delete users, API keys, access-control policies, and reference lists. A hallucinated tool argument from your AI assistant could change incident state or modify your tenant configuration.

Recommended posture:

• Run read-only first. Set GREYMATTER_READ_ONLY=true to register only query tools and make graphql_query reject mutations. Lift it only when you need to write.
• Use a GreyMatter API key scoped to the minimum permissions your use case requires.
• Review every mutating tool call before allowing execution. Claude Desktop requires tool-call approval by default — keep that enabled.
• Treat the API key with the same care as portal admin credentials, because functionally it is one.
• The HTTP transport binds to 127.0.0.1 by default. Do not expose it to the public internet without adding authentication.

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.

[!IMPORTANT] Each user can hold one API key, and keys cannot be renewed — creating a new key invalidates the old one. Requests authenticate with the X-API-KEY header (not your email/password login).

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

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.