> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallwatch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Let Claude and other AI agents drive Tallwatch through the Model Context Protocol: list monitors, open incidents, and manage your account in plain language.

The Tallwatch MCP server exposes your account to AI agents like Claude as a small set of tools. Once it's connected, you can ask Claude to "list the monitors that are down" or "create an HTTP monitor for my staging API" and it calls Tallwatch for you. It's a thin, typed client over the [public REST API](/api/api-keys): it never touches the database and holds no server state, so everything it can do is gated by the scope of the API key you give it.

<Note>
  MCP (Model Context Protocol) is an open standard for connecting AI agents to
  tools. The Tallwatch server speaks it over stdio, so any MCP client (Claude
  Desktop, Claude Code, and others) can use it.
</Note>

## Before you start

* An [API key](/api/api-keys) with the scopes you want the agent to have. Use a `read` key if the agent should only look, or a `write` key if it should also create monitors and resolve incidents.
* The `@tallwatch/mcp` package built locally (`pnpm --filter @tallwatch/mcp build`), or the `tallwatch-mcp` binary installed.

## Configure it

The server reads two environment variables:

| Variable            | Required | Default                     | Notes                                                     |
| ------------------- | -------- | --------------------------- | --------------------------------------------------------- |
| `TALLWATCH_API_KEY` | yes      | none                        | A `tw_live_…` key. Create one in **Settings → API keys**. |
| `TALLWATCH_API_URL` | no       | `https://api.tallwatch.com` | Override for self-hosted or staging.                      |

## Connect Claude Desktop

Add the server to `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`), pointing the command at the built entry:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "tallwatch": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/dist/index.js"],
      "env": {
        "TALLWATCH_API_KEY": "tw_live_your_key_here",
        "TALLWATCH_API_URL": "https://api.tallwatch.com"
      }
    }
  }
}
```

If the `tallwatch-mcp` binary is installed globally, you can point the command at it directly and drop `TALLWATCH_API_URL` to use the default:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "tallwatch": {
      "command": "tallwatch-mcp",
      "env": {
        "TALLWATCH_API_KEY": "tw_live_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config. The Tallwatch tools then appear in the client.

## Tools

The server registers ten tools. Read tools work with a `read` key; write tools need a `write` key.

| Tool                   | What it does                                                                  | Scope   |
| ---------------------- | ----------------------------------------------------------------------------- | ------- |
| `list_monitors`        | List every monitor in the organization.                                       | `read`  |
| `get_monitor`          | Fetch one monitor by id with its current state.                               | `read`  |
| `create_monitor`       | Create a monitor (type, config, regions, interval, and more).                 | `write` |
| `pause_monitor`        | Pause a monitor so it stops being scheduled.                                  | `write` |
| `resume_monitor`       | Resume a paused monitor.                                                      | `write` |
| `list_incidents`       | List incidents newest-first, with optional `status` and `monitor_id` filters. | `read`  |
| `get_incident`         | Fetch one incident by id with its full event timeline.                        | `read`  |
| `acknowledge_incident` | Acknowledge an open incident, with an optional note.                          | `write` |
| `resolve_incident`     | Manually resolve an incident, with an optional note.                          | `write` |
| `list_status_pages`    | List every status page in the organization.                                   | `read`  |

<Note>
  `acknowledge_incident` and `resolve_incident` work with a `write`-scoped key.
  A `read`-only key calling a write tool gets a clear `403` from the API.
</Note>

## What you can ask

With the server connected, you drive Tallwatch in plain language. A few examples:

<AccordionGroup>
  <Accordion title="Triage what's broken">
    "Which monitors have an open incident right now? Show me the most recent
    event on each." The agent calls `list_incidents` filtered to open, then
    `get_incident` for the detail.
  </Accordion>

  <Accordion title="Stand up a new monitor">
    "Create an HTTP monitor for [https://staging.acme.com](https://staging.acme.com) checking every minute
    from three regions." The agent calls `create_monitor` with the right config.
    This needs a `write` key.
  </Accordion>

  <Accordion title="Close the loop after a fix">
    "I just deployed the fix. Acknowledge the incident on the checkout API and
    leave a note that the rollback is done." The agent calls
    `acknowledge_incident` with your note. This needs a `write` key.
  </Accordion>

  <Accordion title="Pause noisy checks during maintenance">
    "Pause the monitors tagged `legacy` while we migrate." The agent finds them
    with `list_monitors` and calls `pause_monitor` on each. This needs a `write`
    key.
  </Accordion>
</AccordionGroup>

<Tip>
  Hand the agent a `read` key when you only want it to observe. Scope
  enforcement happens API-side on every call, so a read key physically cannot
  create or resolve anything, no matter what you ask.
</Tip>