# Tatami MCP Server

Customer-facing remote MCP server for Tatami. It runs as a stateless Cloudflare Worker at:

```txt
https://mcp.tatamimonitor.com/mcp
```

The Worker is a thin proxy over the customer API documented in Tatami at `/account/teams/:team_id/api`. Customers bring their own Tatami platform access token. The Worker does not store tokens.

## Tools

`search_events`

Search delivery events for concrete examples. Wraps:

```txt
POST /api/v1/teams/:team_id/projects/:project_id/events/search
```

Arguments:

- `team_id` and `project_id`, optional when the MCP connection sends `X-Tatami-Team-Id` and `X-Tatami-Project-Id`
- `filters`, using `{ field, operator, value }`
- `occurred_at`, using `{ gte, lte }` ISO timestamps
- `limit`, from 1 to 100

`get_top_reasons`

Fetch last-24-hour deferral and bounce reason breakdowns. Wraps:

```txt
GET /api/v1/teams/:team_id/projects/:project_id/events/reasons
```

Arguments:

- `team_id` and `project_id`, optional with headers
- `limit`, from 1 to 100, default 20

`query_report`

Query deliverability report sections. Wraps:

```txt
POST /api/v1/teams/:team_id/projects/:project_id/reports/query
```

Arguments:

- `team_id` and `project_id`, optional with headers
- `sections`, any of `stats`, `time_series`, `bounce_analysis`, `breakdowns`, `top_lists`
- `filters`, using `{ field, operator, value }`
- `occurred_at`, using `{ gte, lte }` ISO timestamps
- `breakdown_type`, required when `sections` includes `breakdowns`
- `breakdown_limit`, from 1 to 100, default 25 upstream

`get_query_reference`

Return static filter fields, operators, event types, report sections, breakdown types, and query rules. This tool does not call the Tatami API.

## Customer connection

Create a Tatami API key from the API page, then configure the MCP client with headers.

```json
{
  "mcpServers": {
    "tatami": {
      "url": "https://mcp.tatamimonitor.com/mcp",
      "headers": {
        "Authorization": "Bearer <token from Manage API Keys>",
        "X-Tatami-Team-Id": "<team id>",
        "X-Tatami-Project-Id": "<project id>"
      }
    }
  }
}
```

`team_id` and `project_id` are numeric IDs from the Tatami API page dropdowns. Tool arguments can override the header defaults.

## Local development

Use Node 22 or newer. The latest Wrangler release requires Node 22.

Install dependencies:

```sh
npm install
```

Run type checks:

```sh
npm run typecheck
```

Run the Worker locally:

```sh
npm run dev
```

Connect MCP Inspector to:

```txt
http://localhost:8787/mcp
```

Use the same headers as production.

## Cloudflare

`wrangler.jsonc` points the Worker at `mcp.tatamimonitor.com` as a custom domain and sets:

```json
{
  "TATAMI_BASE_URL": "https://tatamimonitor.com"
}
```

Cloudflare can deploy this repository directly from GitHub. No Worker secrets are required for v1 because customers pass their own Tatami API keys on each MCP connection.

## API rules

- `tenant_id` is webhook/customer metadata, not the Tatami team ID.
- Event search defaults to the last 7 days.
- Report queries default to the last hour.
- Queries are capped at a 60-day `occurred_at` range.
- Event search returns up to 100 events and has no pagination cursor.
- Report breakdowns return up to 100 rows. `breakdown_limit` defaults to 25 upstream.
- Tatami rate-limits the three live endpoints together at 100 requests per hour per token.