Overview

The Gremlin MCP (Model Context Protocol) server exposes Gremlin’s reliability management APIs through an MCP-compatible service. It lets developers, SREs, and reliability engineers query service inventories, dependencies, experiment results, pricing/usage data, and generate reliability reports programmatically from an MCP-capable client (for example, Claude Desktop or other LLM clients that implement MCP).

This service is useful when you want to integrate Gremlin data into automated reliability reports, run analysis across teams and services, extract recent chaos experiments, or build dashboards that consume Gremlin telemetry without querying the REST API directly. The MCP layer standardizes requests and makes it straightforward to ask natural-language agents for reliability insights anchored to your account data.

Features

Service inventory and metadata listing (scores, targets, descriptions)
Dependency graph retrieval and dependency-level risk analysis
Retrieval of configured status checks and policy evaluations
Experiment and test history: recent tests, experiment details, and results
Reliability report generation per service and date
Usage, pricing, and billing breakdowns by tracking period
Client (agent) and attack summaries for team-level operational visibility
Test-suite retrieval for team-wide test orchestration
Integration-ready (MCP) endpoint for use with LLM-based developer tools

Installation / Configuration

Prerequisites:

Node.js 22+ recommended (server will run on Node 18+, tests require 20.19+ or 22.12+)
npm
make
Valid Gremlin API key

Clone and install:

git clone [email protected]:gremlin/mcp.git gremlin-mcp
cd gremlin-mcp
make install
make

Environment (example .env or shell export):

# .env
GREMLIN_API_KEY=your_gremlin_api_key_here

Run the server (example):

# run built MCP server
node build/main.mjs

Claude Desktop MCP client example configuration (add to claude_desktop_config.json):

{
  "mcpServers": {
    "gremlin-mcp": {
      "command": "node",
      "args": ["/path/to/gremlin-mcp/build/main.mjs"],
      "env": {
        "GREMLIN_API_KEY": "your_gremlin_api_key_here"
      }
    }
  }
}

Replace /path/to/gremlin-mcp with the actual repository path.

Available Tools

The MCP service exposes a set of tools (RPC-style calls) for reliability workflows. Common tools and required parameters:

Tool	Purpose	Required parameters
list_services	List RM services with metadata and targeting	none
get_service_dependencies	Get dependencies for a service	teamId, serviceId
get_service_status_checks	Get status checks for a service	teamId, serviceId
list_service_risks	List identified risks for a service	teamId, serviceId
get_reliability_report	Generate a report for a service/date	teamId, serviceId, date (YYYY-MM-DD, optional)
get_reliability_experiments	Get recent experiments for a service	teamId, serviceId, dependencyId (opt), testId (opt), limit (opt)
get_pricing_report	Usage/pricing report for date range	startDate, endDate, trackingPeriod (opt)
get_client_summary	Agent/client summary for a team	teamId, start, end, period
get_attack_summary	Attack summary for a team	teamId, start, end, period
get_recent_reliability_tests	Recent tests for a team	teamId, pageSize (opt), pageToken (opt)
get_current_test_suite	Current test suite for team(s)	teamId (opt)

Notes:

Date parameters use YYYY-MM-DD.
teamId and serviceId are required for most service-specific calls.

Use Cases

List all services and their reliability scores
- Call: list_services
- Use this to get an inventory and prioritize follow-up investigations.
Identify critical shared dependencies across services
- Steps: list_services → get_service_dependencies for each service → detect shared dependencies → feed into list_service_risks and policy reports for coverage analysis.
Generate a per-service reliability report for a date
- Call: get_reliability_report with teamId, serviceId, and date (or omit date to use today)
- Output is suitable for inclusion in incident postmortems and monthly SRE reviews.
Audit scheduling gaps and expired policy evaluations
- Steps: get_service_status_checks and policy evaluation data → compute % expired (exclude ignored/SPOF dependencies) → produce per-service metrics and timelines.
Billing and usage reconciliation
- Call: get_pricing_report with startDate and endDate to obtain agent/target usage broken down by tracking period.
Summarize recent chaos experiments and tests
- Call: get_reliability_experiments and get_recent_reliability_tests to extract recent attack/test metadata, targets, outcomes, and IDs for follow-up or replay.

Example: ask an MCP-capable client “Which of our RM services have more than 3 expired policy evaluations over the last 6 weeks and are not marked ignored or SPOF?” The client can call get_service_status_checks and list_service_risks per service, compute the metric, and return a ranked list plus suggested remediation steps.

Testing

Integration tests use vitest and require a GREMLIN_API_KEY. Run tests:

# ensure environment is set
env $(cat .env | xargs) make test

Tests are skipped if GREMLIN_API_KEY is not set.

Notes and Troubleshooting

Authentication errors usually indicate an invalid or missing GREMLIN_API_KEY; verify the environment variable and key scope.
Use UUIDs for teamId/serviceId as returned by list_services; many endpoints will reject friendly names.
Default values are used where applicable (e.g., result limits, date defaults) — supply explicit parameters for deterministic reports.

Gremlin MCP Server Reliability Analysis and Reports