Install first, onboard through MCP

Install. Sign in. Paste one prompt.

Three steps: 1. Install MCP — add the hosted server to your client. 2. Sign in with OAuth — your client’s native login creates or connects your Free AlertsDown account and verifies your email. 3. Copy onboarding prompt — paste one MCP onboarding prompt that asks for your URLs and plan choice, then creates your monitors using only AlertsDown MCP tools. No API key is needed on the OAuth path. A paid plan is an upgrade you choose afterward via card checkout or x402 payment — the agent always asks for your explicit approval before paying and never auto-pays.

Install MCP & start onboarding See the flow
  • Free or paid plans
  • Card or x402
  • OAuth login
  • Claude Code
  • Codex
  • Cursor
  • Windsurf
  • OpenClaw
  • Hermes Agent
Hosted MCP endpoint Free & paid
https://api.alertsdown.com/api/mcp
Transport
Streamable HTTP
Cold start
POST /api/agent/bootstrap
Auth
Authorization: Bearer · authHeader · OAuth
Revisions
2026-07-28 · 2025-11-25

Start here

Choose your coding agent

Install the hosted MCP server, sign in with OAuth to create or connect your Free account, then copy one MCP onboarding prompt. A paid plan is an upgrade you choose afterward. The REST API-key bootstrap is kept as a collapsed fallback for headless, CI, or legacy clients.

Claude Code

Onboard Claude Code on AlertsDown

Step 1

Install MCP

Claude Code discovers OAuth metadata from the endpoint automatically. Add the HTTP server, then complete the native OAuth login. No bearer header is needed for OAuth.

Add the hosted MCP server

Run this in a terminal. No bearer header is needed for OAuth.

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

Step 2

Sign in with OAuth
Complete the OAuth login

In Claude Code, run /mcp and approve the AlertsDown OAuth prompt. From a terminal you can also run:

claude mcp login alertsdown

OAuth creates or connects your Free AlertsDown account and verifies your email. A paid plan is an upgrade you choose in Step 3.

Step 3

Copy onboarding prompt

After OAuth connects your Free account, copy this MCP onboarding prompt into Claude Code. It uses only AlertsDown MCP tools to ask once for your URLs and plan choice, create your monitors, and finish by reporting your plan and monitors. No email is requested — OAuth already verified it.

Preview MCP onboarding prompt (wraps on mobile) 
Onboard me on AlertsDown using only the AlertsDown MCP tools.
Do not use curl, Bash, shell commands, direct HTTP requests, the /api/agent/bootstrap endpoint, /api/agent/plans, any credential-claim endpoint, or API keys. My OAuth login already created or connected my Free account and verified my email — do not ask me for my email.
1. Call get_account to confirm my connected account, then call list_plans to discover the available plans, monitor limits, billing periods, and prices. Never hard-code plan IDs or prices.
2. Ask me once for the URLs I want monitored and whether I want the Free plan or a paid plan (and which billing period). Do not ask for my email — OAuth already verified it.
3. Free choice: call the setup_monitors MCP tool with my URLs to create the monitors in one idempotent batch. setup_monitors is idempotent — retrying with the same URLs safely deduplicates, so a lost or uncertain response can be retried with the same inputs.
4. Paid choice (upgrade): call purchase_plan with the chosen planId and billingPeriod to upgrade my account. Present the checkout or payment information to me and require my explicit approval before proceeding. Never auto-pay.
   - Card: purchase_plan returns a checkout URL. Hand me the URL to open and complete in a browser. A checkout link is not proof of payment — wait for my confirmation that payment succeeded before calling setup_monitors.
   - x402: purchase_plan returns the amount, asset, network, and recipient. Show me those details and ask for my explicit confirmation before I approve. Never auto-pay. After I approve and the payment is fulfilled, call setup_monitors.
   - After the paid upgrade is fulfilled, call setup_monitors with my URLs to create the monitors.
5. Call list_urls to show the created monitors, then call get_account to report my plan, monitor limits, and entitlement end date.
6. Never call /api/agent/bootstrap, /api/agent/plans, or any credential-claim endpoint directly. Use only the MCP tools: get_account, list_plans, setup_monitors, purchase_plan, list_urls.
7. Respect API limits: honor the rate limits and request quotas the backend returns. On HTTP 429, read Retry-After and use bounded exponential backoff; do not retry aggressively. Do not retry authentication, validation, permission, payment, or other non-transient 4xx failures.

Headless, CI, or legacy clients

API-key bootstrap (headless, CI, or legacy clients)

If OAuth is unavailable, use the REST API-key bootstrap flow. Create an API key from Account → MCP/API Keys and store it in your user-level secret environment as ALERTSDOWN_MCP_API_KEY. Never paste the secret into chat or commit it.

export ALERTSDOWN_MCP_API_KEY="admcp_your_secret_here"
claude mcp add --transport http alertsdown https://api.alertsdown.com/api/mcp \
  --header "Authorization: Bearer $ALERTSDOWN_MCP_API_KEY" \
  --scope user
API-key bootstrap onboarding prompt

The full API-key bootstrap prompt creates the account, chooses a plan, and connects MCP using a bearer key. It is the only path that uses an API key.

Preview API-key bootstrap prompt (wraps on mobile) 
Set up AlertsDown for me.
1. Read https://api.alertsdown.com/.well-known/alertsdown-agent.json and call GET https://api.alertsdown.com/api/agent/plans to discover the live plans, billing periods, prices, and payment methods. Never hard-code plan IDs or prices.
2. Ask me once for my real email address, the URLs I want monitored, and whether I want the Free plan or a paid plan (and which billing period and payment method). Never invent an email.
3. Free choice: call POST https://api.alertsdown.com/api/agent/bootstrap with { email, urls, clientInfo: { name: "claude-code" } }. A 201 response returns { account, apiKey: { secret, scopes, auth, authHeader }, mcp, next } with a newly issued secret. Store the API key immediately in my user-level secret environment as ALERTSDOWN_MCP_API_KEY; never print it in chat or write it to a repository. Resolve the auth header from response.authHeader ?? response.auth; treat authHeader as canonical and keep auth for legacy responses. If neither field is present, fall back to "Authorization: Bearer <API_KEY>". Never print, log, or commit a real API key; reference the secret ALERTSDOWN_MCP_API_KEY.
4. Paid choice: call POST https://api.alertsdown.com/api/agent/bootstrap with { email, urls, planId, billingPeriod, paymentMethod, clientInfo: { name: "claude-code" } }. A 202 response returns { purchaseId, claimToken, checkout?, x402?, statusUrl, claimUrl }. Keep the valid claim token secure until the credential is stored.
   - Card: hand me the checkout URL to open and complete in a browser. A checkout link is not proof of payment. Poll statusUrl until status is "fulfilled", then POST the claimToken to claimUrl to retrieve the API key. Claims are idempotent: if a claim response is lost or uncertain, retry with the same valid claim token and you will receive the same stored key. Do not retry with a different or invented token.
   - x402: only when the manifest reports x402Enabled and the plan offers an x402_30d billing period. Ask me for explicit confirmation before paying. Show me the amount, asset, network, and recipient from the manifest products or the 202 response x402 field before I approve. After I approve, POST to the x402PaymentUrl with a payment-signature header to pay. Then poll statusUrl until status is "fulfilled", and POST the claimToken to claimUrl to retrieve the API key. Claims are idempotent: retry with the same valid claim token if a response is lost. Never auto-pay without my explicit confirmation.
   - The credential-claim response exposes the same { apiKey: { secret, scopes, auth, authHeader } } shape as the Free flow. Credential claims are idempotent: if the response is lost, retrying with the same valid claim token returns the same secret. Never use a different or invented token. Resolve the auth header from response.authHeader ?? response.auth; treat authHeader as canonical and keep auth for legacy responses. If neither field is present, fall back to "Authorization: Bearer <API_KEY>". Never print, log, or commit a real API key; reference the secret ALERTSDOWN_MCP_API_KEY. Paid and Free onboarding must produce identical canonical auth guidance.
   - No account, monitors, or key are created until payment is fulfilled.
5. Configure the returned hosted MCP endpoint (https://api.alertsdown.com/api/mcp) with the resolved auth header and the key from ALERTSDOWN_MCP_API_KEY.
6. Prefer this client's native MCP configuration or current MCP SDK over hand-rolled JSON-RPC. AlertsDown supports MCP 2026-07-28 over Streamable HTTP and the legacy 2025-11-25 revision. For 2026-07-28, do not send initialize, initialized, or Mcp-Session-Id; every request is independent. If calling the endpoint directly, include the required per-request _meta fields (io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities) and HTTP headers (MCP-Protocol-Version, Mcp-Method, and Mcp-Name for tools/call, prompts/get, and resources/read). Use server/discover when capability or version discovery is needed, and retry with a mutually supported revision when the server returns UnsupportedProtocolVersionError. Do not hand-roll raw JSON-RPC when the client already supports MCP.
7. Ask me for the 6-digit email verification code and verify the primary email contact through MCP.
8. List the monitors and report the plan limits and entitlement end date.
9. No-argument MCP tools — get_account, list_plans, list_contacts, list_agent_webhooks — accept an empty {} input. Call them normally; do not invent dummy parameters or a requestId workaround.
10. Before email verification, the provisional bootstrap key includes monitors:read, so list_urls and get_url work and only return monitors belonging to the bootstrapped account. Provisional monitor access does not imply unrestricted API access; stay within the scopes returned during onboarding.
11. Respect API limits: honor the rate limits, request quotas, and payload-size limits the backend returns or documents. On HTTP 429, read Retry-After and use bounded exponential backoff; do not retry aggressively. Do not retry authentication, validation, permission, payment, or other non-transient 4xx failures. Keep requests account-scoped and within the API-key scopes returned during onboarding.
12. If bootstrap returns HTTP 409 with code "email_already_registered", stop onboarding. Explain that the account already exists and no new API key was created. Ask me to sign in or use the account recovery link sent by email. After I sign in, direct me to Account → MCP/API Keys. Tell me to create and configure the API key myself. Never ask me to paste the API key into the agent chat. Tell me to notify the agent only after configuration is complete. Only then may the agent use the MCP list_plans and purchase_plan tools for paid plan changes; an existing card subscription returns a billing portal URL instead of a duplicate checkout.

What happens

Install, sign in, then onboard through MCP

Install the hosted MCP server, sign in with OAuth to create or connect your Free account, then paste one MCP onboarding prompt. Your agent uses only AlertsDown MCP tools — no curl, Bash, direct HTTP, bootstrap endpoints, or API keys on the OAuth path.

  1. Step 1Install MCP

    Add the hosted AlertsDown MCP server to your client using its install command or config. The installation command is the first visible action in each client tab above. No API key or bearer header is needed for the OAuth path.

  2. Step 2Sign in with OAuth

    Complete your client’s native OAuth login. OAuth creates or connects your Free AlertsDown account and verifies your email — there is no separate email-verification step and no API key to copy on this path. A paid plan is an upgrade you choose afterward.

  3. Step 3Copy onboarding prompt

    Copy the MCP onboarding prompt and paste it into your agent. The agent uses only AlertsDown MCP tools — get_account, list_plans, setup_monitors, list_urls — to ask once for your URLs and plan choice, create your monitors in one idempotent batch, and finish by reporting your plan and monitors. It never uses curl, Bash, direct HTTP, /api/agent/bootstrap, /api/agent/plans, credential-claim endpoints, or API keys.

  4. Step 4Paid upgrade (optional)

    Card: purchase_plan returns a checkout URL for you to open and complete in a browser. x402: purchase_plan returns the amount, asset, network, and recipient, and the agent asks for your explicit confirmation before paying — it never auto-pays. After the upgrade is fulfilled, the agent creates your monitors with setup_monitors.

  5. Step 5Headless, CI, or legacy clients

    If your client cannot do OAuth, expand the collapsed Headless, CI, or legacy clients fallback in each client tab. That path uses the REST API-key bootstrap flow: the agent calls POST https://api.alertsdown.com/api/agent/bootstrap, stores the returned secret as ALERTSDOWN_MCP_API_KEY, and configures https://api.alertsdown.com/api/mcp with the canonical Authorization: Bearer header. It is the only path that uses an API key.

x402 payments: When you choose an x402 billing period for a paid upgrade, purchase_plan shows you the amount, asset, network, and recipient, and asks for your explicit confirmation before paying. The agent never auto-pays. Your Free account and monitors already exist — the upgrade takes effect after payment is fulfilled.

Existing account?

OAuth connects your existing account directly — no new account or key is created. For paid plan changes, the agent uses the list_plans and purchase_plan MCP tools; an existing card subscription returns a billing portal URL instead of a duplicate checkout.

Raw HTTP

Protocol details

Only relevant if you call the endpoint directly — the client configs above handle all of this for you.

  • Revision 2026-07-28
  • Auth Bearer · authHeader · OAuth
  • Handshake None
  • Session Stateless

Probe the server with curl

Every modern request sends Mcp-Method plus the protocol version and client capabilities in params._meta; named calls (tools/call, prompts/get, resources/read) also send Mcp-Name. There is no initialize handshake and no session ID — server/discover is the capability probe and each request is authenticated independently.

curl -i https://api.alertsdown.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $ALERTSDOWN_MCP_API_KEY" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "server/discover",
        "params": {
          "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientInfo": { "name": "curl", "version": "0.1" },
            "io.modelcontextprotocol/clientCapabilities": {}
          }
        }
      }'

Clients that still speak the 2025-11-25 initialize handshake are served by the stateless legacy fallback and need none of the modern headers.

Free Builders

MCP access, bounded for a safe start

The Free plan reaches the same hosted MCP surface with plan limits enforced inside every write path.

  • Per key20/min · 200/hour
  • Per user40/min · 400/hour
  • MonitorsPlan URL limit applies
  • ChecksPlan interval floor applies

Your agent reads the live URL limit, minimum interval, and available alert channels from the manifest. Paid plans retain higher MCP request limits.

Capabilities

What your agent can do

Once connected, your AI client can work with live AlertsDown data as part of your normal workflow.

Create and manage monitors

Add, update, or remove monitors for your services without leaving your editor.

Investigate incidents faster

Pull monitor status, recent failures, and response history straight into the conversation.

Keep releases honest

Verify monitors after a deploy before you move on to the next task.

Document reliability work

Use live monitor data to draft incident notes, summaries, and status updates.

In practice

Prompts to try

Once your client is connected, ask it things like:

Add uptime monitoring for the production API and alert me if it stops returning 200.
Show me which monitored endpoints failed after the last deployment.
Check whether the checkout, webhook receiver, and status page are healthy before I announce this release.

FAQ

Frequently asked questions

Is hosted MCP available on the Free plan?

Yes. Free Builders includes hosted MCP, bounded by its monitor and check-interval limits plus tighter per-key and per-user request limits. No card required.

Can I use OAuth instead of an API key?

Yes — OAuth is the preferred path for interactive clients. This deployment supports OAuth (authorization code + PKCE) for Claude Code, Codex, Cursor, Windsurf, OpenClaw, and Hermes Agent. Install the server, complete your client’s native OAuth login, then copy the MCP onboarding prompt. OAuth creates or connects your Free account and verifies your email, so no API key is needed. API keys remain supported only as a collapsed fallback for headless, CI, and legacy clients.

How does the install-first onboarding flow work?

Three steps: 1. Install MCP — add the hosted AlertsDown MCP server to your client with its install command or config. 2. Sign in with OAuth — complete your client’s native OAuth login, which creates or connects your Free account and verifies your email. 3. Copy onboarding prompt — paste the MCP onboarding prompt so your agent creates your monitors using only AlertsDown MCP tools. No API key is needed on the OAuth path.

Can I choose a paid plan during agent onboarding?

Yes. OAuth connects your Free account first. During onboarding you can stay on Free or upgrade to a paid plan and billing period. The paid selection is an upgrade afterward — the agent calls purchase_plan, presents the checkout or payment details, and requires your explicit approval before proceeding. Your Free account and monitors already exist, so there is no "no account until payment" wait on the OAuth path.

How do agent payments work?

After OAuth connects your Free account, a paid upgrade uses the purchase_plan MCP tool. For card, it returns a checkout URL for you to open and complete in a browser. For x402, it shows you the amount, asset, network, and recipient, and asks for your explicit confirmation before paying — the agent never auto-pays. After the upgrade is fulfilled, the agent creates your monitors with the setup_monitors MCP tool.

What happens if I already have an AlertsDown account?

OAuth connects your existing account directly — no new account or key is created. For paid plan changes on an existing account, the agent uses the list_plans and purchase_plan MCP tools; an existing card subscription returns a billing portal URL instead of a duplicate checkout. If you are on the headless API-key fallback path and bootstrap returns 409 email_already_registered, sign in or use the account recovery link sent by email, then create and configure an API key yourself from Account → MCP/API Keys. Never paste the API key into agent chat.

Does the OAuth path ask for my email again?

No. OAuth already establishes and verifies your email, so the MCP onboarding prompt never asks for it. The agent only asks for the URLs you want monitored and whether you want the Free plan or a paid upgrade.

Which clients can I configure?

The install-first flow supports Claude Code, Codex, Cursor, Windsurf, OpenClaw, and Hermes Agent through the hosted AlertsDown MCP endpoint.

How should my agent authenticate to hosted MCP?

On the OAuth path, your client handles authentication natively — no API key is needed. On the headless API-key fallback, connect to https://api.alertsdown.com/api/mcp using the header Authorization: Bearer <API_KEY>. Bootstrap and credential-claim responses expose auth and authHeader; treat authHeader as the canonical machine-readable instruction and keep auth for legacy responses, falling back to Authorization: Bearer <API_KEY> only when neither is present. Store the key in your runtime secret store as ALERTSDOWN_MCP_API_KEY and never paste it into source files or shared configuration.

Do MCP tools require dummy parameters?

No. No-argument tools such as get_account, list_plans, list_contacts, list_agent_webhooks accept an empty {} input. Call them normally — do not invent dummy parameters or a requestId workaround.

Is this the same as MCP Alerts?

Hosted MCP lets your AI client connect to AlertsDown. MCP alerts are a separate feature for monitoring your own or vendor MCP servers and receiving alerts when they break.

Hand monitoring to your agent

Choose your client, install MCP, sign in with OAuth, then copy the MCP onboarding prompt. Headless or CI? Use the collapsed API-key bootstrap fallback in each client tab.

Install MCP & start onboarding View agent manifest