# Let an agent operate a project

> minket-mcp lets an agent such as Claude operate a project: domains, keys, logs and events, sending with a dry run, suppressions, webhook replays, received mail and contact lookups.

Source: https://docs.minket.com/mcp/
Updated: 2026-10-29

`minket-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. An agent connected to it can check a domain's DNS, read request logs and the event feed, send mail after a dry run, manage suppressions, replay webhooks, read received mail and look contacts up. Every tool is a call to the [TypeScript SDK](https://docs.minket.com/sdks/), and every input schema is the API's own zod schema, so a tool accepts exactly what the API accepts.

## Connect it

```sh
pnpm --filter @minket/mcp build      # writes apps/mcp/dist/bin.mjs
claude mcp add minket -e MINKET_API_KEY=minket_test_... -- node /path/to/minket/apps/mcp/dist/bin.mjs
```

`MINKET_BASE_URL` points it at another API address. Other clients take the same command in their configuration:

```json
{
  "mcpServers": {
    "minket": {
      "command": "node",
      "args": ["/path/to/minket/apps/mcp/dist/bin.mjs"],
      "env": { "MINKET_API_KEY": "minket_test_..." }
    }
  }
}
```

## Choose the key

The key decides what the agent can do, so give it the narrowest that does the job:

| Key | The agent can |
|---|---|
| Test (`minket_test_…`) | Read the project and send [test mail](https://docs.minket.com/sending/#test-mode); it changes nothing live mail shares ([scopes](https://docs.minket.com/keys/#scopes)). Start here. |
| `inbound_read` | Read received mail and its attachments, nothing else. |
| `sending_access` | Send, reschedule, cancel and upload attachments; nothing else. |
| Live `full_access` | Everything, including keys, domains and real sends. |

The agent should call `whoami` first: it reports the key's project, environment, mode and scope. Keys are never returned, except the token of a key made with `create_key`, once.

## Tools

| Area | Read-only | Changes something |
|---|---|---|
| Keys | `whoami`, `list_keys` | `create_key`, `revoke_key` |
| Domains | `list_domains`, `get_domain`, `get_domain_reputation` | `create_domain`, `verify_domain` |
| Sending | `list_emails`, `get_email`, `get_email_events`, `list_templates`, `preview_template` | `send_email`, `cancel_email` |
| Logs and events | `list_logs`, `get_log`, `list_events`, `get_event` | |
| Suppressions | `list_suppressions` | `add_suppression`, `remove_suppression` |
| Webhooks | `list_webhooks`, `list_webhook_deliveries` | `replay_webhook`, `test_webhook` |
| Inbound | `list_inbound`, `get_inbound`, `get_inbound_attachment` | |
| Contacts | `find_contact` (by id or address), `list_contacts`, `list_contact_consent` | |
| Broadcasts and automations | `list_broadcasts`, `get_broadcast`, `list_automations`, `list_automation_runs` | |

Read-only tools carry `readOnlyHint`, and `revoke_key`, `cancel_email` and `remove_suppression` carry `destructiveHint`, so a client can ask before running them. Broadcasts and automations are read-only on purpose: sending a broadcast or publishing an automation stays with people, in the console or with [`minket api`](https://docs.minket.com/cli/#any-operation).

Results are the API's JSON, also as structured content. A failure comes back as an error result with the API's code, what to do next, the validation issues and the request id, so the agent can correct the call or report it.

## Sending with a dry run

`send_email` takes the [send request](https://docs.minket.com/sending/): `from`, `to`, `subject` and `text` or `html`, or a hosted `template` with `variables`, plus attachments, `scheduled_at`, `via` a mailbox and `idempotency_key`. With `dry_run: true` nothing is sent. The server checks:

- the body against the API's schema, with the same messages;
- the sender: the domain of `from` belongs to the project, is verified, has sending on and passes authentication (or the mailbox of `via` is connected);
- every recipient against the suppression list, for the email's stream;
- the template, rendered with the variables, and its subject.

```json
{
  "dry_run": true,
  "would_send": true,
  "mode": "live",
  "sender": { "domain": "mail.acme.example", "status": "verified", "sending": "enabled", "authentication": "passing" },
  "recipients": [
    { "address": "jane@example.com", "suppressed": null },
    { "address": "old@example.com", "suppressed": { "reason": "hard_bounce", "stream": null } }
  ],
  "template": { "id": "receipt", "subject": "Your receipt for order 10452" },
  "problems": [],
  "notes": ["Suppressed recipients are accepted and skipped (email.suppressed): old@example.com."]
}
```

A clean dry run is a strong hint, not a promise: the send itself also applies content checks, the kill switch, rate limits and the daily cap. When the agent sends for real it should pass an `idempotency_key` and reuse it on a retry, so the email goes out once.

## Treat mail as data

Received messages and contact fields come from outside parties. `get_inbound` says so in its description, and the agent should never follow instructions found in a message body, a subject or an attachment. Prefer an `inbound_read` key when the agent only reads mail.