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.
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?"
alert_signup_link
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:
AWS · GitHub · Stripe · Cloudflare · Google Cloud · Microsoft Azure · OpenAI · Anthropic (Claude) · Slack · Microsoft 365 · Datadog · Twilio · SendGrid · PayPal · DigitalOcean · New Relic · Zoom · Jira · Linear · Fastly · 1Password · Mailgun · Zendesk · CircleCI · Adobe Cloud · Apple · Firebase · Oracle Cloud … and ~22 more.
Slug resolution (typo-tolerant)
Every tool that takes a slug argument runs the input
through a four-stage resolver before giving up:
- Exact slug match: fastest path. Slugs are
lower-kebab-case, e.g.
amazon-web-services,microsoft-365. - Curated alias map: for the shorthand humans say that doesn't match a slug. Examples below.
- 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.
- 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 |
|---|---|
aws | amazon-web-services |
gcp | google-cloud |
azure | microsoft-azure |
m365 / o365 | microsoft-365 |
github actions | github |
is jira down? | jira |
planetscle | planetscale (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
| Layer | Limit | What you'll see |
|---|---|---|
| Burst per key | 30 requests / minute | limit_type: "burst_per_key" |
| Monthly per key | 500 calls / 30-day period | limit_type: "monthly_per_key" |
| Monthly per account | Pro: 500 calls. Team: 2,000 calls. Across all keys, each in its current period. | limit_type: "monthly_per_account" |
| Public endpoint, per IP | 30 requests / minute, 500 / day | HTTP 429 |
| Public endpoint, through an assistant's own network | Counted for the assistant as a whole, with a much higher ceiling | HTTP 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
| HTTP | Code | Meaning |
|---|---|---|
| 401 | missing_or_invalid_authorization_header | No Authorization: Bearer pk_… on the request. |
| 401 | invalid_or_revoked_api_key | Key doesn't exist, or you revoked it. |
| 402 | mcp_requires_pro_plan | The account is on Free. Keyed access needs Pro or Team; it stops if the account moves back to Free. |
| 429 | rate_limit_exceeded | One of the three keyed rate-limit layers hit. Body lists which, with the limit and usage for monthly caps. |
| 200 (with isError) | provider_not_found | Slug didn't resolve to anything in the catalog. |
| 200 (with isError) | provider_not_in_your_stack | Provider exists but isn't popular / not monitored. See the scope rule. |
| 200 (with isError) | component_not_found | Component name didn't match anything for that provider. |
| 200 (with isError) | multiple_matches | Component 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).
Links in responses
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.
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
Email [email protected].
Didn't find what you needed? Let us know and we'll add it to the guides.