Help center

MCP endpoint

Pingoru's MCP endpoints plug live status data into any MCP-compatible AI assistant: Claude Desktop, Claude Code, Cursor, Cline, Zed, Goose, and others. A public endpoint needs no key; a keyed endpoint on Pro and Team adds your own monitors and alerts. This page is the reference: how to connect, the full tool catalog, what each tool returns, rate limits, errors, and the rules for which providers your assistant can ask about.

← All guides

Looking for the marketing overview? See the MCP feature page. This article assumes you've already decided to use it and want to know how it works.

The API & MCP page showing the account's call counter for this period and one API key with its own usage and a Revoke button.
The API & MCP page at /app/api-keys, with the account's calls this period. Create a key here, then paste it into your AI client's MCP server config.

What you need

There are two endpoints:

  • Public, no key: https://pingoru.io/api/mcp-public/. No account needed. It has the seven catalog tools and answers about every provider Pingoru tracks, limited per IP to 30 requests a minute and 500 a day. Claude Code: claude mcp add --transport http pingoru https://pingoru.io/api/mcp-public/. In Claude on the web or desktop, add Pingoru from Claude's connector directory (see Pingoru in Claude), or under Settings, Connectors, Add custom connector with that URL; there is nothing to sign in to.
  • Keyed: https://mcp.pingoru.io/, for Pro ($9/month) and Team accounts. It adds three account tools that see your own monitors and alerts.

For the keyed endpoint you need:

  • A Pingoru Pro or Team plan (or the Team trial). On Free the API & MCP page shows an upgrade screen.
  • An API key created at /app/api-keys (up to 10 active keys). Keys start with pk_; the secret is shown once at creation time and only a hash is stored, so there's no way to recover a lost secret. Paste it into your AI tool's config immediately.
  • An MCP-compatible client. /features/mcp#setup and the API & MCP page have copy-paste config for the major ones; if your client isn't listed it just needs the endpoint URL and a Bearer token.

The keyed endpoint

https://mcp.pingoru.io/

Streamable HTTP only (there is no SSE endpoint), stateless: every request stands alone. Speak JSON-RPC 2.0 per the MCP specification; tools are surfaced via the standard tools/list and called via tools/call. Clients that only start local servers, like Claude Desktop, connect through the mcp-remote bridge; Claude Code connects directly with --transport http.

Authentication

Every request to the keyed endpoint needs an Authorization: Bearer pk_… header:

curl -sS https://mcp.pingoru.io/ \
  -H "Authorization: Bearer pk_YOUR_SECRET_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Keys are revocable from the dashboard. Revoking takes effect on the next request.

We log call metadata (timestamp, tool name, slug argument, status code, duration) for 90 days for forensics and abuse detection. We do not log response bodies, prompts, or anything from the conversation that produced the call.

Tool reference

10 tools on the keyed endpoint, all read-only (the public endpoint has the catalog tools only). Tools split into two scopes:

  • Catalog tools: on the keyed endpoint they work against any provider in the curated popular set or any provider you have a monitor on (see Provider scope for why); on the public endpoint, against any provider. Catalog tools: provider_status, provider_components, component_status, provider_incidents, incident_detail, search_providers, alert_signup_link.
  • Account tools only see your own monitors and notifications. Account tools: my_monitors, my_active_alerts, my_recent_incidents.

provider_status

Get the current status, any active incidents and upcoming maintenance for a status-page vendor.

Signature: provider_status(slug: string)

Returns: { slug, name, health, pingoru_url, alert_url?, alert_note?, active_incident_count, active_incidents, upcoming_maintenance, last_checked_at, status_url }

Try it: "Is GitHub down right now?"

provider_components

List a provider's components with their current status; optionally filter to non-operational only.

Signature: provider_components(slug: string, only_problematic?: boolean)

Returns: { slug, name, pingoru_url, components: [{ component_id, name, group_name?, status, last_observed_at }] }

Try it: "Which Cloudflare components are degraded?"

component_status

Pinpoint the status of a single component by name (case-insensitive substring match).

Signature: component_status(slug: string, component: string)

Returns: { component_name, group_name?, status, pingoru_url, in_active_incident, current_incident? }

Try it: "What's the status of EC2 us-east-1?"

provider_incidents

Recent incidents and maintenance for a provider (last 1–30 days) with status, times, affected components and links, with optional filter to a single component.

Signature: provider_incidents(slug: string, days?: number = 7, component?: string)

Returns: { slug, name, pingoru_url, incidents: [{ id, title, status, started_at, resolved_at, duration_minutes, impact, affected_components, url, pingoru_url }], maintenance: [...] }

Try it: "Any AWS issues this week?"

incident_detail

Full record for one incident or maintenance: status, start/resolve times, duration, affected components, links and every status update with its timestamp.

Signature: incident_detail(slug: string, incident_id: number)

Returns: { incident: {...}, updates: [{ posted_at, body, status }] }

Try it: "Walk me through the May 3 Stripe outage."

search_providers

Find providers by name or slug. Use when the agent does not know the exact slug.

Signature: search_providers(query: string, limit?: number = 10)

Returns: [{ slug, name, category, is_active, pingoru_url }]

Try it: "Look up that DBaaS, planetscale?"

The Pingoru page where you can enter an email address to be told when a provider's status changes. It creates nothing by itself.

Signature: alert_signup_link(slug: string)

Returns: { slug, name, health, alert_url }

Try it: "Tell me when Revolut is back up."

my_monitors

List all of the caller's monitored services with their current rolled-up health.

Signature: my_monitors()

Returns: [{ public_id, name, provider: { slug, name }, health, active_incident_count, in_maintenance }]

Try it: "What's the health of my entire stack?"

my_active_alerts

Open incidents on the caller's monitored services right now.

Signature: my_active_alerts()

Returns: [{ monitor_id, monitor_name, provider_slug, incident: { id, title, started_at, impact, components } }]

Try it: "Is anything I monitor broken right now?"

my_recent_incidents

Resolved incidents on the caller's monitors over the last N days (max 30).

Signature: my_recent_incidents(days?: number = 7)

Returns: [{ monitor_id, provider_slug, incident: {...} }]

Try it: "What burned us this week?"

Provider scope on the keyed endpoint

On the keyed endpoint, catalog tools (provider_status, provider_components, component_status, provider_incidents, incident_detail) gate which providers your assistant can ask about. The rule is simple:

  • The 50 most-asked-about vendors are always available: AWS, GitHub, Stripe, Cloudflare, GCP, Azure, OpenAI, Anthropic, Slack, M365, Datadog, Twilio, SendGrid, etc.
  • Any provider you have a monitor on is available. Go to /app/monitors, click + Add Monitor, and search for the vendor.

Asking about a provider that's neither popular nor monitored returns:

{
  "error": "provider_not_in_your_stack",
  "slug": "linear",
  "name": "Linear",
  "hint": "MCP can only query providers in the curated popular set
           ... or providers you have a monitor on. Add a free
           monitor for 'Linear' from /app/monitors and the agent
           will see it on the next call."
}

Why the gate? It stops a single account from harvesting our 8,000+ catalog and republishing it. It doesn't stop you from asking about the long tail: add a monitor first, or ask through the public endpoint, which covers every provider.

The 50-vendor popular set (sample)

The popular set covers the SaaS/cloud vendors that ~95% of "is X down?" questions land on:

Slug resolution (typo-tolerant)

Every tool that takes a slug argument runs the input through a four-stage resolver before giving up:

  1. Exact slug match: fastest path. Slugs are lower-kebab-case, e.g. amazon-web-services, microsoft-365.
  2. Curated alias map: for the shorthand humans say that doesn't match a slug. Examples below.
  3. Fuzzy search via Meilisearch: typo-tolerant name and slug matching. Re-ranked locally by character overlap so incident-title noise can't drag the wrong vendor to the top.
  4. Stop-word-stripped retry: "is jira down?" becomes "jira" before the second pass.

The kinds of input the resolver handles:

Your assistant says…Resolves to
awsamazon-web-services
gcpgoogle-cloud
azuremicrosoft-azure
m365 / o365microsoft-365
github actionsgithub
is jira down?jira
planetscleplanetscale (typo-tolerant)

When fuzzy fallback fires, the tool's response includes matched_via: "fuzzy" and echoes the original query so the assistant can confirm with the user before quoting the result.

Rate limits

LayerLimitWhat you'll see
Burst per key30 requests / minutelimit_type: "burst_per_key"
Monthly per key500 calls / 30-day periodlimit_type: "monthly_per_key"
Monthly per accountPro: 500 calls. Team: 2,000 calls. Across all keys, each in its current period.limit_type: "monthly_per_account"
Public endpoint, per IP30 requests / minute, 500 / dayHTTP 429
Public endpoint, through an assistant's own networkCounted for the assistant as a whole, with a much higher ceilingHTTP 429

Hitting a keyed limit returns HTTP 429 with a structured JSON-RPC error. Each key counts calls over a rolling 30-day period: it starts when the key is created and restarts with the first call after it ends, not on the first of the month. Only successful calls count. On Team, one key still stops at 500, so spread heavy use over several keys to use the account's 2,000. Need more headroom for a power workflow? Contact us for a per-account override.

Errors

HTTPCodeMeaning
401missing_or_invalid_authorization_headerNo Authorization: Bearer pk_… on the request.
401invalid_or_revoked_api_keyKey doesn't exist, or you revoked it.
402mcp_requires_pro_planThe account is on Free. Keyed access needs Pro or Team; it stops if the account moves back to Free.
429rate_limit_exceededOne of the three keyed rate-limit layers hit. Body lists which, with the limit and usage for monthly caps.
200 (with isError)provider_not_foundSlug didn't resolve to anything in the catalog.
200 (with isError)provider_not_in_your_stackProvider exists but isn't popular / not monitored. See the scope rule.
200 (with isError)component_not_foundComponent name didn't match anything for that provider.
200 (with isError)multiple_matchesComponent substring matched several components. The response lists candidates so the assistant can ask you which one.

Incident lookback

Tools that take a days argument (provider_incidents, my_recent_incidents) are capped at 30 days. Asking for older history is intentionally not supported: the protocol is for "what's broken / has been broken recently?" questions, not historical research. For older history, point your assistant at the upstream vendor's own status page (each tool surfaces status_url in its response).

Every response names the page it came from, as pingoru_url. For a service that is the provider page, for a list of incidents the outage history page, and for a single incident that incident's own page. Incidents also carry url, the vendor's own report, and service responses carry status_url, the vendor's status page. On the public endpoint provider_status adds alert_url, the page where an email alert for that service can be set up. While the service has an open incident, an alert_note beside it says what the link is for.

Setup recipes

Configure your AI tool by pasting your API key and the endpoint URL into the right config file. The setup tabs on /features/mcp#setup, and on the API & MCP page once you have a key, give a filled-in snippet for each supported tool: copy, paste, restart. Tools we've tested:

  • Claude Desktop–Anthropic's desktop chat app. The most polished MCP experience and our recommended starting point.
  • Claude Code–Anthropic's CLI for terminal-based pair programming. Add the Pingoru MCP server with a single command.
  • Cursor–AI-first code editor (VS Code fork). MCP support is built in via Settings → MCP.
  • Cline–Open-source autonomous coding agent for VS Code. Configure via the MCP Servers tab in the sidebar.
  • Continue.dev–Open-source AI coding assistant for VS Code and JetBrains. Add MCP servers under mcpServers in config.yaml.
  • Zed–High-performance native editor by ex-Atom team. MCP support via the assistant-servers config.
  • Goose–Block's open-source local-first AI agent. MCP-native; add the server with goose configure.
  • ChatGPT (via bridge)–ChatGPT doesn't speak MCP natively yet. The community bridges (e.g. mcp-bridge) translate MCP into ChatGPT's connector format.

Anything else that speaks MCP works too, see the "My tool isn't here" tab for the raw config shape.

The API & MCP page with one active key and the 'Plug it in' section, showing setup tabs for Claude Desktop, Claude Code, Cursor, Cline and other tools.
Once you have a key, Plug it in on the API & MCP page gives a filled-in config for each AI tool.

Worked example

Asking Claude Desktop "is GitHub having any problems right now?" produces a tool call like this under the hood:

POST https://mcp.pingoru.io/
Authorization: Bearer pk_…
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "provider_status",
    "arguments": { "slug": "github" }
  }
}

And gets back:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{
        \"slug\": \"github\",
        \"name\": \"GitHub\",
        \"health\": \"operational\",
        \"pingoru_url\": \"https://pingoru.io/providers/github\",
        \"alert_url\": \"https://pingoru.io/providers/github?notify=1\",
        \"active_incident_count\": 0,
        \"long_running_incident_count\": 0,
        \"active_incidents\": [],
        \"upcoming_maintenance\": [],
        \"last_checked_at\": \"2026-05-06T22:36:38Z\",
        \"status_url\": \"https://www.githubstatus.com\"
      }"
    }],
    "isError": false
  }
}

Claude then phrases that as "GitHub looks healthy: no active incidents as of two minutes ago" and you move on with your day.

Troubleshooting

"Unauthorized" or "401" from my AI tool

Three usual causes: (1) the key was revoked from /app/api-keys; (2) you pasted the public ID (k_…) instead of the secret (pk_…); (3) the Authorization header isn't reaching us: some MCP clients require the header in a headers object inside the server config rather than a top-level auth field.

"provider_not_in_your_stack" but I'm sure I have a monitor

Check the slug. The MCP resolves "Github Actions" to github, not to a separate github-actions provider: there is no Actions-only monitor. If you do have a monitor on the parent provider, the gate should let you through; if it still rejects, the slug your assistant generated may not match a real provider, try search_providers("…") first.

Hit the monthly cap mid-session

On Pro the account cap (500) equals one key's cap, so a second key doesn't add calls. On Team the account cap is 2,000 but each key still stops at 500, so a second key does help. Each key's count restarts 30 days after its period began (rolling, not calendar). For quick "is X down?" questions you can also use the public endpoint, which has its own per-IP limits. If that doesn't fit your workflow, contact us for a per-account override.

Can the assistant change anything?

No. Read-only by design: there's no MCP tool that pauses a monitor, acknowledges an incident, or edits anything in your account. Write operations would raise consent and audit questions we want to think through carefully before exposing to an agent loop.

Bug or feature request

Didn't find what you needed? Let us know and we'll add it to the guides.