MCP reference

Pingwell’s MCP server lets an AI agent read and configure one Pingwell workspace. It speaks the Model Context Protocol over streamable HTTP. Set up with your agent covers connecting each client.

Endpoint


URL	`https://mcp.pingwell.dev/mcp`
Transport	Streamable HTTP, `POST` only. Each request stands alone: there are no sessions to resume.
Auth	OAuth 2.1 with PKCE through the client’s own sign-in (scopes `pingwell:read` and `pingwell:write`, one workspace per connection), or a workspace API key as `Authorization: Bearer <key>`
Scope	One workspace, the one approved at sign-in or the API key’s own

A request without valid credentials gets 401 with a WWW-Authenticate header pointing at the server’s OAuth metadata, which MCP clients follow to sign in.

Tools

Tools work in the connected workspace, so none takes a workspace id. Every tool says whether it only reads, whether it changes things, and whether it reaches outside Pingwell, so your client can ask before the ones that change things.

Setting a project up

Tool	What it does
`get_setup_context`	The plan, what it allows and what is used, the regions, the ping base URL, the records an earlier setup made (by key) and the ones made another way. Agents call it first.
`plan_setup`	Describe the whole setup, with a stable key for each record, and get back what applying it would create, change or remove, and anything the plan does not allow. Nothing changes yet.
`apply_setup`	Carry out a plan once the person agrees. Returns heartbeat ping URLs and DNS records. Reusing a key later updates that record.
`get_approval`	Whether the person has approved a removal. Plans that remove records, and the delete tools, wait for their approval.

Workspace

Tool	What it does
`get_workspace`	The plan, what it allows, what is used, and the base URL pings go to.
`list_probe_regions`	The regions checks run from.
`get_overview`	What is up and down right now.

Monitors

Tool	What it does
`list_monitors`, `get_monitor`	Read uptime checks and their state.
`create_monitor`	Add an HTTP check (a URL) or a TCP check (a host and port).
`update_monitor`	Change any field.
`pause_monitor`, `resume_monitor`	Stop and restart checking. Nothing is lost.

Heartbeats

Tool	What it does
`list_heartbeats`, `get_heartbeat`	Read heartbeats, with their ping URLs.
`create_heartbeat`	Watch a scheduled job. Returns the ping URL and examples.
`update_heartbeat`	Change the name, period, grace or labels.
`pause_heartbeat`, `resume_heartbeat`	Stop and start expecting pings.

Status pages

Tool	What it does
`list_status_pages`, `get_status_page`	Read pages, their components and domain state.
`create_status_page`, `update_status_page`	Create a page or change its name, slug, visibility, language or password.
`set_status_page_components`	Choose what the page shows: monitors, heartbeats, fixed statuses or regions.
`publish_status_page`	Push the page live now.
`set_custom_domain`	Serve the page on your hostname. Returns the CNAME and TXT records to create. Pro and Unlimited.
`get_custom_domain_status`	Whether the domain is live yet, and the records it still needs.

Alerts

Tool	What it does
`list_channels`, `create_channel`, `update_channel`	Email to members, Slack, Discord, webhooks and PagerDuty.
`test_channel`	Send a real test message. It reaches people, so agents say so first.
`set_check_channels`	Choose which channels a monitor or heartbeat alerts.
`list_channel_groups`, `create_channel_group`, `update_channel_group`	Named sets of channels.

Docs

Tool	What it does
`search_docs`	Search this documentation.

Errors

A refused change comes back as a tool error the agent can act on:

Invalid input names each field and what is wrong with it.
A plan limit says which limit and its value, and carries the link to upgrade under Settings → Billing. Agents relay it rather than retry.
Not found means the id is not in this workspace.
Rate limited means too many changes in a minute; wait and retry.

Every tool goes through the same API the panel uses, with the same checks. Nothing an agent does can get around a plan limit or a role.

Security

One workspace per connection. Approving an agent grants it the workspace you pick, with your role there, and no other.
Revocable. Settings → Connected agents lists every agent with when it last acted. Revoking one ends its access at once, and removing a person from the workspace ends the access of every agent they connected.
Short-lived tokens. Access tokens last an hour and refresh tokens rotate on every use. A stolen refresh token that is used twice revokes the whole connection.
Deletes need you. No tool deletes anything directly. A delete returns a link you open in Pingwell to confirm.
No secrets in code. Agents put ping URLs in configuration, never in committed files, and never write API keys or tokens anywhere.