MCP Integration Guide

MicroGemLabs exposes an MCP server that lets any MCP-compatible AI agent — Claude Code, Cursor, Hermes Agent, Grok Bot, or a custom agent — read and (for GemSmart business teams) write your business/monitoring data through a standard protocol: monitoring, logging, and alerting data across all seven products, the MicroGemAI memory system, GemScrape web-data tools, and GemSmart CRM/booking data.

The catalog has 31 tools total: 20 covering the seven devops products plus MicroGemAI memory and GemScrape, and 11 GemSmart business-data tools (6 read-only + 5 writes — see "GemSmart tools" below) for GemSmart business teams. Which tools a given team's tools/list call returns depends on that team's enabled products and team type — an engineering team with nothing enabled yet sees the devops tools only; a GemSmart business team sees its 11 gemsmart tools plus any devops tools for products it has enabled.

All MCP tool calls require a team API key. Generate one in Settings → Account → API Keys (key creation is owner/admin-gated — MCP keys are operator-grade, see "Write tools" below).

The API key is passed as a Bearer token on every request:

Authorization: Bearer mgl_team_xxxxxxxxxxxxx

API keys are scoped to a single team. All data returned — and every write — is limited to that team's resources.

> OAuth is planned, not yet available. The PAT-style Bearer API key above is the only supported auth method today. Don't wait on OAuth to connect — the API key works with every MCP client that supports a custom Authorization header.

The server endpoint is /api/mcp on your MicroGemLabs deployment, e.g. https://microgemlabs.ai/api/mcp (or your team's staging domain). All examples below use that placeholder — swap in your actual deployment URL.

Claude Code

Claude Code's claude mcp add command adds an HTTP-transport MCP server with a custom header. The exact flags can shift between Claude Code versions, so verify against claude mcp add --help if this doesn't match what you see:

claude mcp add --transport http microgemlabs \
  https://microgemlabs.ai/api/mcp \
  --header "Authorization: Bearer mgl_team_xxxxxxxxxxxxx"

If your Claude Code version's CLI differs, the config file form is stable across versions — add this to your MCP config (.mcp.json / ~/.claude.json, wherever your Claude Code setup stores it):

{
  "mcpServers": {
    "microgemlabs": {
      "type": "http",
      "url": "https://microgemlabs.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer mgl_team_xxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Hermes Agent

Add to your Hermes Agent MCP configuration:

# ~/.hermes/mcp_servers.yaml
servers:
  - name: microgemlabs
    url: https://microgemlabs.ai/api/mcp
    auth:
      type: bearer
      token: mgl_team_xxxxxxxxxxxxx

Grok Bot / other remote-MCP clients

Any agent that supports remote MCP with a custom Bearer header can connect directly:

Server URL: https://microgemlabs.ai/api/mcp
Authorization: Bearer mgl_team_xxxxxxxxxxxxx

query_monitors

Get the current status of all uptime monitors (PulseGuardPlus).

query_incidents

Get recent incidents across ALL products — PulseGuardPlus downtime, CronKeeper missed pings, LogVault alerts, CertGuard expiry warnings, CronRunner failures, HookRelay forward failures.

search_logs

Search log entries in LogVault with full-text search.

query_cron_checks

Get cron job monitor status from CronKeeper.

query_certs

Get SSL certificate and domain registration status from CertGuard.

query_scheduled_jobs

Get scheduled HTTP job status from CronRunner.

query_webhooks

Get webhook endpoint status from HookRelay.

query_errors

List ErrorGuard error groups — tracked application errors grouped by fingerprint, newest activity first.

get_oncall_status

Get current on-call schedule status.

get_platform_health

Comprehensive health overview of ALL products in one call. This is the most useful tool for general "how are things?" queries.

search_memory

Search MicroGemAI's accumulated knowledge base.

correlate_events

Find events across ALL products that occurred around a specific time. The most powerful tool for incident investigation.

Incident Investigation with Hermes Agent

You: What caused the API outage at 3 AM?

Hermes Agent:
  → [calls get_platform_health]
  → [calls query_incidents with hours=12]
  → [calls correlate_events with timestamp=2026-04-20T03:00:00Z]
  → [calls search_logs with query="error" hours=2]

"Based on the data, here's what happened:

The API gateway monitor went down at 2:58 AM. LogVault shows a spike of 
'SSL handshake failed' errors starting at 2:45 AM. CertGuard reports that 
the api.example.com certificate expired at 2:30 AM. CronKeeper shows the 
cert-renewal cron job has been in 'late' status for 3 days.

Root cause: The SSL certificate renewal cron job stopped running, the cert 
expired, and the API started rejecting HTTPS connections.

Fix: Renew the cert manually, then investigate why the renewal cron failed."

Proactive Check with Claude

You: @microgemlabs Are there any issues I should know about?

Claude:
  → [calls get_platform_health]
  → [calls query_certs with expiring_within_days=14]

"Your infrastructure looks mostly healthy. Two items to note:

1. The staging.example.com SSL cert expires in 9 days. Consider 
   renewing early.
2. CronRunner shows the 'analytics-sync' job has 2 consecutive 
   failures. The last error was 'Connection refused' — your analytics 
   endpoint may be down."

These tools allow agents to interact with the runbook system (now part of the unified Skills library — see /agent/skills?type=runbook). Trust levels apply — see Runbook Actions in the MicroGemAI guide.

list_runbooks

List available runbook action templates for this team.

• category — Filter: restart, scale, cache, rollback, dns, custom, or all (default)
• active_only — Boolean, default true

execute_runbook

Trigger a runbook action. Trust levels apply: manual templates execute immediately when called by an authenticated agent, auto_approval templates return a pending status with approval link, full_auto templates execute immediately.

• template_id (required) — ActionTemplate ID from list_runbooks
• incident_id — Link execution to an incident
• incident_source — Product that created the incident
• variables — Key-value pairs for {{variable}} substitution
• reasoning — Why you're executing this (stored in audit trail)

check_execution_status

Poll for the result of a runbook execution.

• execution_id (required) — ActionExecution ID from execute_runbook

suggest_runbook

Find matching runbooks for an incident description. Uses trigger pattern matching and past execution history.

• product (required) — Where the incident occurred
• incident_title (required) — Description of the incident
• error_message — Error message for better matching

Example: Full Incident Investigation + Auto-Fix

You: My API is down, check MicroGemLabs and fix it.

Agent:
  → [calls get_platform_health]
  → [calls query_incidents with product=pulseguardplus, status=active]
  → [calls search_logs with query="error" hours=1]
  → [calls correlate_events with timestamp of the incident]
  → [calls suggest_runbook with product=pulseguardplus, incident_title="API Gateway DOWN"]
  → [calls execute_runbook with template_id of "Restart API Workers"]
  → [calls check_execution_status to verify success]
  → [calls query_monitors to confirm recovery]

"The API Gateway went down at 3:02 AM due to connection pool exhaustion.
LogVault showed 'max connections reached' errors starting at 2:45 AM. I
executed the 'Restart API Workers' runbook — workers restarted in 3.2s
and the API is now responding normally (avg 142ms)."

Eleven tools for businesses running on GemSmart — six read-only, five writes — so a client-owned external agent (Grok Bot via its remote-MCP support, Claude Code, Cursor, or anything MCP-speaking) can use GemSmart as its structured data source AND take real CRM/booking actions on the business's behalf. These tools only work for GemSmart business teams; a devops-only team gets a clean "GemSmart tools are not enabled for this team" error if it calls one.

get_business_profile

The business's public profile — name, services (price/duration), hours, service area, contact info. Public-safe subset only: no payment configuration, no intake question internals.

list_leads

List CRM leads, newest first.

list_bookings

List bookings/appointments. Returns id, service, customer name, start/end time, and status — never intake answers or payment details, even though the underlying data includes them for the owner portal.

list_followups

List CRM follow-ups due today or overdue, oldest-due first.

get_reviews_summary

Rating now, 7-day rating delta, new-review count, and a handful of recent reviews (author/rating/text).

get_daily_snapshot

The morning briefing numbers — follow-ups due, new leads, missed/handled calls, bookings today, no-shows, reputation/mentions context. The "what should I know this morning?" tool — call this first for a general status question.

Write tools

Key custody warning

Treat your mgl_team_… key like a password — for write-capable teams, more so, since it's an operator-grade credential. If you connect it to a third-party agent and later stop using that tool, rotate the key.

A key also unlocks intake links whose pages can show a returning customer's prior intake answers — another reason to rotate keys you no longer use.

MCP has two independent rate-limit buckets, both enforced server-side (no per-client action needed beyond backing off on a rate-limit response):

• tools/call, per team: 120 requests/minute. Applies after authentication succeeds, keyed on the authenticated team. For bulk queries, use get_platform_health (one call for everything) instead of querying each product individually.
• Failed authentication, per IP: 20 attempts/minute. Applies to bad/missing/revoked Bearer tokens, keyed on the caller's IP — this is what stops key-guessing/enumeration bursts. A single mistyped key won't trip it; hammering the endpoint with bad keys will.

A rate-limited call gets back a JSON-RPC error with code: -32005 (an implementation-defined code in the JSON-RPC reserved -32000..-32099 server-error range — there's no MCP-standard code for this yet) and a Retry-After header/data.retryAfterSec field telling you how long to wait.

All tools return data scoped to the authenticated team. You cannot access other teams' data, and no write tool can affect any team other than the one the API key belongs to. Most tools (all devops/monitoring tools, and six of the eleven GemSmart tools) are read-only — no tool can create, modify, or delete resources beyond what the write tools above explicitly allow. Use the MicroGemLabs dashboard for anything not covered by a write tool.