MCP Server

PulsAPI publishes a remote Model Context Protocol server so an AI agent can check whether a vendor is down instead of guessing from stale training data.

Connecting is a URL and a browser approval. There is no API key to generate, and nothing secret ends up in a config file.

The endpoint

The five tools

Every tool is read-only and reads public vendor status. None of them can see your dashboards, alert rules, team, or subscriptions, and there is no write path at all.

The live list is whatever tools/list returns to your connected client; the backend registry is the source of truth and this table mirrors it.

Connect it

Claude Code

claude mcp add --transport http --scope user pulsapi https://www.pulsapi.com/api/mcp

Then run /mcp, choose pulsapi, and approve in the browser. Drop --scope user to register the server for the current project only.

Claude Desktop

Settings → Connectors → Add custom connector, and paste the URL:

https://www.pulsapi.com/api/mcp

The consent screen opens as soon as the connector is added. There is no config file to edit.

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json for just this one:

{
  "mcpServers": {
    "pulsapi": {
      "url": "https://www.pulsapi.com/api/mcp"
    }
  }
}

Safe to commit, since there is no secret in it. Settings → MCP will show pulsapi as Needs login; click it and approve.

VS Code

.vscode/mcp.json, read by Copilot agent mode:

{
  "servers": {
    "pulsapi": {
      "type": "http",
      "url": "https://www.pulsapi.com/api/mcp"
    }
  }
}

Note servers, not mcpServers. VS Code is the one client that uses a different key.

Codex CLI, and any stdio-only client

A client that can only launch a local command reaches the server through the mcp-remote bridge, which performs the OAuth flow on its behalf and caches the token under ~/.mcp-auth:

[mcp_servers.pulsapi]
command = "npx"
args = ["-y", "mcp-remote", "https://www.pulsapi.com/api/mcp"]

The first run opens a browser. Later runs reuse the cached token until it expires.

Any other client

If it speaks Streamable HTTP it needs the URL and nothing else, because the server tells it where to authenticate. See the handshake for yourself:

curl -i -X POST https://www.pulsapi.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

That returns 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/api/mcp, which is the first link in the discovery chain a client follows to find the authorization server.

How authorization works

Your client needs one piece of information, the URL. Everything else is discovered:

1. An unauthenticated call returns 401 with WWW-Authenticate: Bearer resource_metadata=… (RFC 9728).
2. The client fetches /.well-known/oauth-protected-resource/api/mcp, which names the authorization server.
3. It fetches /.well-known/oauth-authorization-server for the endpoints (RFC 8414).
4. It registers itself at the registration endpoint (RFC 7591). Nobody has to enrol the client or provision it first.
5. It opens the consent screen at /oauth/authorize, you approve, and it exchanges the code with PKCE for a token bound to this endpoint as its audience (RFC 8707).

Credentials are short and rotating: authorization codes live 60 seconds, access tokens 1 hour, and refresh tokens 30 days, rotating on every use. Presenting an already-spent refresh token revokes the whole chain.

Every connected client is listed under Settings → MCP server, where you can disconnect one without rotating anything else.

Headless callers: use an API key

A CI job has no browser and nobody to press Approve, so the OAuth flow cannot complete. That is the one place where a long-lived key is the right tool and not a shortcut:

curl -s https://www.pulsapi.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pb_your_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authorization: Bearer pb_your_key_here works identically, for clients that only support bearer tokens. Keys live in Settings → API Keys and need the mcp:invoke scope.

Worked example

Asking an agent "is Cloudflare having problems, and does it affect eu-west?" turns into get_service_status for the headline and get_component_status for the regional breakdown.

The second call does the real work here. Most vendors publish a component breakdown, but only about a quarter of them say which region is affected. The measured numbers are in the Status Page Transparency Report.

Limits worth knowing

• Read-only, public data. All five tools read the same vendor status the website serves. There is no customer or workspace data behind any of them, and no tool writes anything.
• A lapsed plan returns 403, not 401. The caller is authenticated and simply not entitled, so re-authenticating would not help, and a 401 would send a well-behaved client into a pointless re-authorization loop.
• Results reflect what each vendor publishes. Where a vendor publishes nothing parseable, PulsAPI falls back to a direct reachability check, which is a weaker global up/down signal rather than per-component detail.

Related

• Developer hub: the REST API, OpenAPI spec, CLI, and this server
• The PulsAPI MCP server announcement
• What OAuth 2.1 actually requires from a remote MCP server
• Browse every tracked vendor