# ITOC360 MCP Server

An [MCP](https://modelcontextprotocol.io) server that lets AI agents raise and resolve incidents in [ITOC360](https://www.itoc360.com).

When an agent notices something a human needs to act on, it calls `send_alert`. ITOC360 pages whoever is on call through the tenant's escalation policy — SMS, voice call, mobile push, email — and keeps escalating until someone acknowledges. When the problem clears, the agent calls `resolve_alert` and the page stops.

## Requirements

- Node.js 20 or newer
- An ITOC360 account and a **source token**

## Getting a token

1. Sign in to ITOC360 and open **Sources**
2. Create a source (a Prometheus/Alertmanager source works — this server speaks that format)
3. Copy the source token

The token identifies both the tenant and the source, so keep it secret.

## Configuration

Add the server to your MCP client. For Claude Desktop, edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "itoc360": {
      "command": "npx",
      "args": ["-y", "@itoc360/mcp"],
      "env": {
        "ITOC360_TOKEN": "your-source-token"
      }
    }
  }
}
```

For Claude Code:

```bash
claude mcp add itoc360 --env ITOC360_TOKEN=your-source-token -- npx -y @itoc360/mcp
```

### Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `ITOC360_TOKEN` | yes | — | Source token from the ITOC360 source page |
| `ITOC360_BASE_URL` | no | `https://api.itoc360.app` | Override the API host |
| `ITOC360_TIMEOUT_MS` | no | `30000` | Per-request timeout in milliseconds |

## Tools

### `send_alert`

Raises an alert and starts the escalation policy.

| Argument | Required | Description |
|---|---|---|
| `fingerprint` | yes | Stable identifier for the problem, e.g. `checkout-api::latency` |
| `summary` | yes | One-line title shown as the alert headline |
| `description` | no | Longer explanation on the alert detail page |
| `severity` | no | `critical`, `error`, `warning` (default) or `info` |
| `labels` | no | Extra key/value labels, e.g. `{"service": "checkout"}` |
| `generator_url` | no | Link back to the dashboard or run that surfaced the problem |

### `resolve_alert`

Closes an alert raised earlier and stops further escalation.

| Argument | Required | Description |
|---|---|---|
| `fingerprint` | yes | Must match the fingerprint used to raise the alert |
| `summary` | yes | One-line note recorded with the resolution |
| `description` | no | Longer explanation of what resolved the problem |

## Fingerprints and deduplication

The fingerprint is how ITOC360 decides whether two alerts describe the same problem.

Reuse the same fingerprint for the same underlying issue. Raising an alert again with a fingerprint that is already open updates the existing alert rather than opening a second one and paging someone twice — which is why both tools are safe to retry.

`resolve_alert` needs the same fingerprint to find the alert and close it, so pick something an agent can reconstruct: `service::check` reads better than a random UUID.

## Wire format

This server posts the Prometheus Alertmanager webhook body, byte-compatible with the other ITOC360 SDKs. An alert raised from here deduplicates against one raised from the Go, Python, Node or .NET SDK as long as the fingerprints match.

## Using the client directly

The package also exports the pieces the server is built from, for use outside MCP:

```ts
import { Itoc360Client, Severity } from '@itoc360/mcp';

const client = new Itoc360Client({ token: process.env.ITOC360_TOKEN });

await client.sendAlert({
  fingerprint: 'checkout-api::latency',
  summary: 'Checkout API p99 above 2s',
  severity: Severity.Critical,
  labels: { service: 'checkout', env: 'prod' },
});
```

Failures raise typed errors: `ValidationError` before anything is sent, `ApiError` (with `unauthorized`, `subscriptionInactive` and `retryable` flags) for a non-2xx response, and `TransportError` when the request never reached ITOC360.

## Development

```bash
npm install
npm test        # builds, then runs the unit and MCP protocol tests
```

## License

Apache-2.0