ReliaQuest GreyMatter MCP Server

Um servidor do Model Context Protocol que expõe a API GraphQL de Autoatendimento do ReliaQuest GreyMatter para assistentes de IA.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP ReliaQuest GreyMatter

PyPI version Python versions License: MIT CI

Um servidor Model Context Protocol que expõe a API GraphQL Self-Service do ReliaQuest GreyMatter para assistentes de IA. Ele fornece 146 ferramentas em 22 domínios — Incidentes, Tarefas, Detecções, Playbooks, Casos, Alertas DRP, Ativos, Identidades, Listas de Referência, Usuários e mais — além de uma graphql_query genérica como alternativa para qualquer coisa não coberta por uma ferramenta dedicada. O conjunto de ferramentas é gerado diretamente da coleção de API do fornecedor, portanto permanece fiel à superfície real da API, e foi verificado contra o schema GraphQL ativo.

[!IMPORTANT] Projeto não oficial. Este é um servidor MCP independente, construído pela comunidade, desenvolvido com base na documentação pública da API da ReliaQuest. Ele não é um produto oficial da ReliaQuest e não é afiliado, endossado ou suportado pela ReliaQuest, LLC. "ReliaQuest" e "GreyMatter" são marcas registradas da ReliaQuest, LLC. Para suporte oficial da plataforma GreyMatter ou da própria API, entre em contato diretamente com a ReliaQuest em greymattersupport@reliaquest.com.

[!WARNING] Software beta — ainda não recomendado para ambientes de produção. Este projeto está em desenvolvimento ativo. A superfície de ferramentas e os formatos individuais das ferramentas podem mudar entre versões menores, e nem todos os endpoints foram exaustivamente testados contra todas as configurações de conta/entitlement. Use em um escopo não produtivo até estar confiante no comportamento para o seu caso de uso.

Este servidor pode executar ações destrutivas no seu ambiente GreyMatter. As ferramentas podem fechar e cancelar incidentes/casos/tarefas, executar playbooks de resposta e criar ou excluir usuários, chaves de API, políticas de controle de acesso e listas de referência. Um argumento alucinado de ferramenta do seu assistente de IA pode alterar o estado de incidentes ou modificar a configuração do seu tenant.

Postura recomendada:

  • Execute somente leitura primeiro. Defina GREYMATTER_READ_ONLY=true para registrar apenas ferramentas de consulta e faça graphql_query rejeitar mutações. Remova isso apenas quando precisar escrever.
  • Use uma chave de API GreyMatter com escopo para as permissões mínimas que seu caso de uso exige.
  • Revise cada chamada de ferramenta mutável antes de permitir a execução. O Claude Desktop exige aprovação de chamada de ferramenta por padrão — mantenha isso habilitado.
  • Trate a chave de API com o mesmo cuidado que as credenciais de administrador do portal, porque funcionalmente é isso que ela é.
  • O transporte HTTP vincula-se a 127.0.0.1 por padrão. Não o exponha à internet pública sem adicionar autenticação.

Ferramentas

146 ferramentas em 22 domínios (56 consultas + 90 mutações), além da alternativa graphql_query. No modo somente leitura, apenas as 56 consultas (e um graphql_query somente consulta) são registradas.

DomínioConsultasMutaçõesFerramentas notáveis
Incidentes310incidents, incident, health_incidents, acknowledge_incident, assign_incident, add_incident_comment, close_incident, update_incident_state
Tarefas29tasks, task, assign_task, add_task_comment, resolve_task, update_task_state
Detecções61detection_rules, customer_detections, customer_detection, customer_detection_activity_log_entries
Playbooks64playbooks, playbook_runs, playbook_run, recommended_playbooks, run_playbook
Casos29cases, case, create_case, close_case, cancel_case, add_case_comment, update_case_owner
Alertas DRP215drp_alerts, drp_alert, assign_drp_alert, watch_drp_alert, add_drp_alert_comment, update_drp_alert_state
Controle de Acesso DRP34access_control_policies, access_control_resources, create_access_control_policy
Grupos de Acesso79access_groups, pods, roles, permissions, create_role, update_pod
Listas de Referência29reference_lists, reference_list, create_reference_list_row, update_reference_list_column
Usuários29me, user, create_user, disable_user, reset_mfa, resend_invite
Tarefas Discover23discover_tasks, discover_task, assign_discover_task, close_discover_task
Contatos de Emergência24emergency_contacts, create_emergency_contact, update_call_order
Chaves de API13api_keys, create_api_key, delete_api_key_by_id
Ativos11assets, delete_asset
Cliente20customer, customers
Identidades10identities
Indicadores20indicators, indicator
Campos20greymatter_fields, greymatter_field
Gerenciamento de Consultas30integrations, integration, search_history
Dados20data_source_schema, time_buckets
Atividade do Usuário10audits
Utilitários20rate_limit, node

146 ferramentas no total. Destaques:

  • Consultas de listagem (incidents, tasks, assets, detection_rules, cases, …) são paginadas via Relay — passe first/after e leia edges, pageInfo e totalCount. A maioria aceita um filtro de domínio e entrada de ordenação (ex.: incidentFilter, incidentOrder).
  • Consultas de item único (incident, task, case, user, …) recebem um argumento by (ex.: um id ou número de ticket) para buscar um registro com seus detalhes completos e comentários.
  • As mutações do fluxo de trabalho de incidentes cobrem o ciclo de vida do GreyMatter Investigate: acknowledge_incident, assign_incident, add_incident_comment, update_incident_state e close_incident. Os códigos de fechamento de incidentes incluem CUSTOMER_TRUE_POSITIVE, CUSTOMER_FALSE_POSITIVE, CUSTOMER_ANOMALOUS_SAFE, FALSE_POSITIVE_CREATE_TUNING_TICKET, CUSTOMER_SECURITY_CONTROL_TESTING, CUSTOMER_CANCELLED; os estados incluem PENDING_CUSTOMER, PENDING_RQ, RESOLVED, CANCELLED.
  • Responder / playbooks: run_playbook executa um playbook predefinido; playbook_runs e playbook_run leem os resultados da execução.
  • Alternativa graphql_query executa um documento GraphQL arbitrário para qualquer coisa sem uma ferramenta dedicada. No modo somente leitura, ela rejeita mutações.
  • customer_slug em todas as ferramentas substitui o cabeçalho x-reliaquest-customer (OpCo) para aquela chamada específica — consulte Multi-OpCo.
  • rate_limit informa seu orçamento restante de API (a API permite 5000 pontos/hora por conta da empresa; cada nó retornado conta como um ponto).

Consulte docs/ENDPOINTS.md para o mapeamento completo de ferramenta ↔ operação GraphQL.

Início rápido

Instalação

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

# or with pip
pip install greymatter-mcp

Para desenvolvimento a partir do código-fonte:

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

Obtendo uma chave de API

Gere uma chave de API GreyMatter no portal:

  1. No GreyMatter, vá para Configurações → Gerenciamento de Chaves de API.
  2. Clique em Nova Chave de API, escolha uma Data de Expiração (o padrão é 1 ano) e depois Criar Chave.
  3. Copie a chave — ela é exibida apenas uma vez. Esta é sua GREYMATTER_API_KEY.

[!IMPORTANT] Cada usuário pode ter uma chave de API, e as chaves não podem ser renovadas — criar uma nova chave invalida a antiga. As solicitações são autenticadas com o cabeçalho X-API-KEY (não com seu login de e-mail/senha).

Configuração

Copie .env.example para .env e defina:

VariávelObrigatóriaPadrãoDescrição
GREYMATTER_API_KEYsim—Sua chave de API GreyMatter (Configurações → Gerenciamento de Chaves de API)
GREYMATTER_BASE_URLnãohttps://greymatter.myreliaquest.com/graphqlEndpoint GraphQL
GREYMATTER_CUSTOMER_SLUGnão(nenhum)Cabeçalho x-reliaquest-customer (OpCo) padrão para contas multi-OpCo
GREYMATTER_READ_ONLYnãofalseQuando verdadeiro, nenhuma ferramenta de mutação é registrada e graphql_query rejeita mutações
GREYMATTER_TIMEOUTnão60Tempo limite de solicitação em segundos (algumas mutações são lentas no servidor)
LOG_LEVELnãoINFONível de registro de log
MCP_HTTP_HOST / MCP_HTTP_PORTnão127.0.0.1:8765Vinculação do transporte HTTP

Executar

  • stdio (padrão): uv run greymatter-mcp (ou apenas greymatter-mcp se instalado como ferramenta)
  • HTTP: greymatter-mcp --transport http --port 8765

Modo somente leitura

Defina GREYMATTER_READ_ONLY=true para executar o servidor com segurança contra produção. Neste modo:

  • Nenhuma ferramenta de mutação é registrada — apenas as 56 ferramentas de consulta são expostas.
  • A alternativa graphql_query rejeita mutações, portanto só pode executar operações de leitura (robusto contra documentos de mutação com prefixo de fragmento ou BOM).

O modo somente leitura é fortemente recomendado para casos de uso de assistente de analista, painéis e relatórios onde o modelo nunca deve ser capaz de alterar o estado.

Integração com editores

Claude Desktop

Edite 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"
      }
    }
  }
}

Se estiver executando a partir do código-fonte em vez de uma ferramenta instalada, use uv com --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" }
    }
  }
}

Reinicie o Claude Desktop e confirme se greymatter aparece no menu de ferramentas.

Claude Code

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

Multi-OpCo (Header Slug)

Contas GreyMatter que gerenciam múltiplas empresas operacionais (OpCos) usam o cabeçalho x-reliaquest-customer ("Header Slug") para selecionar qual empresa uma solicitação tem como alvo:

  • Defina GREYMATTER_CUSTOMER_SLUG para aplicar um slug padrão a cada solicitação.
  • Passe customer_slug em qualquer chamada de ferramenta individual para substituir o padrão para aquela chamada. Ambos definem o cabeçalho x-reliaquest-customer.

Limites de taxa

A API GreyMatter impõe um limite de 5000 pontos/hora por conta da empresa. Cada entidade de nó retornada conta como 1 ponto, portanto consultas paginadas grandes consomem pontos rapidamente. Use a ferramenta rate_limit para verificar seu uso atual.

Limitações conhecidas

Ferramentas restritas por entitlement. Algumas ferramentas retornam "Você não tem acesso a este item" a menos que sua conta/chave de API tenha licença para o módulo relevante — ex.: drp_alerts, access_control_policies, access_control_resources, discover_tasks, audits. Essas funcionam normalmente para contas com entitlement.

Consultas com múltiplas conexões. Algumas consultas paginam várias conexões aninhadas e expõem múltiplos parâmetros first / after (ex.: cases usa first3/after3 para a lista de nível superior e first/first1/first2 para conexões aninhadas). Sempre defina o parâmetro de tamanho de página externo para limitar os resultados; deixá-lo não definido pode retornar respostas muito grandes e causar tempo limite. Para consultas pesadas (ex.: playbook_run_filter_data), aumente GREYMATTER_TIMEOUT.

Exemplos de prompts

  • "Mostre-me incidentes aguardando ação do cliente." → incidents (filtro em state: PENDING_CUSTOMER).
  • "Reconheça o incidente <id> e atribua-o a mim." → acknowledge_incident → assign_incident.
  • "Resolva o incidente <id> como falso positivo com uma nota de ajuste." → close_incident (closeCode: CUSTOMER_FALSE_POSITIVE).
  • "Quais regras de detecção estão implantadas e quais mapeiam para técnicas MITRE?" → detection_rules.
  • "Liste os 25 casos abertos mais recentes." → cases (defina first3: 25).
  • "Quanto do meu orçamento de limite de taxa da API resta?" → rate_limit.

Como as ferramentas são geradas

As ferramentas são geradas a partir da coleção de API do fornecedor:

python scripts/generate_from_collection.py

Isso regenera os módulos em src/greymatter_mcp/tools/_generated/ e o catálogo em docs/ENDPOINTS.md. Os arquivos gerados não são editados manualmente — altere o gerador (seus mapas OVERRIDES / FIELD_EXCLUSIONS) e regenere.

A coleção de API e outros materiais de referência da ReliaQuest estão no diretório Development Reference/, que é ignorado pelo git: é material proprietário da ReliaQuest e não é redistribuído neste repositório público. Para verificar as ferramentas geradas contra a API ativa, scripts/introspect.py busca o schema GraphQL atual.

Desenvolvimento

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 são publicados no PyPI quando uma tag v* é enviada (veja .github/workflows/release.yml).

Licença

MIT

Suporte

Este é um projeto comunitário não oficial. Para dúvidas sobre a plataforma GreyMatter ou a API, entre em contato com a ReliaQuest em greymattersupport@reliaquest.com. Para problemas com este servidor MCP, abra uma issue no repositório do GitHub.