# MCP Server Reference (@wraps.dev/mcp)

Wraps runs two MCP servers: a hosted one for questions about Wraps, and a local one for your own email stack.

## Hosted server: docs and pricing (no auth)

`https://wraps.dev/mcp` speaks the Model Context Protocol over the Streamable HTTP transport. No API key, no account, no signup — it only reads public product data.

| Tool | Description |
|------|-------------|
| `search_docs` | Search the full Wraps documentation and return matching sections as markdown |
| `get_doc` | Read one Wraps page as markdown |
| `list_docs` | The llms.txt index of every page |
| `estimate_cost` | Monthly Wraps + AWS cost for a send volume, including the account's SES pricing plan |

```json
{
  "mcpServers": {
    "wraps-docs": {
      "type": "http",
      "url": "https://wraps.dev/mcp"
    }
  }
}
```

```bash
curl -s https://wraps.dev/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A manifest covering both servers: https://wraps.dev/.well-known/mcp.json

## Local server: your own email stack

`@wraps.dev/mcp` gives AI agents access to your AWS SES sending history, delivery events, domain status, and suppression list — and, optionally, the ability to send email. Runs locally via stdio; your AWS credentials never leave your machine.

## Prerequisites

- Wraps email stack deployed (`wraps email init`)
- AWS credentials configured in your environment (same profile used for the Wraps CLI)

## Tools

| Tool | Description | Write? |
|------|-------------|--------|
| `send_email` | Send a transactional email via your SES account | Yes — requires `WRAPS_WRITE_ENABLED=true` |
| `list_recent_sends` | List recent sends from your email history | No |
| `get_email_event_log` | Full delivery event log for a message (Send, Delivery, Bounce, Complaint, Open, Click) | No |
| `verify_domain_status` | Verification and DKIM status of a sending domain | No |
| `list_suppressions` | Addresses on your SES suppression list, filterable by BOUNCE or COMPLAINT | No |
| `estimate_cost` | Monthly Wraps + AWS cost for a send volume, including the account's SES pricing plan. Needs no AWS credentials | No |
| `check_send_status` | Poll the outcome of a `pending_approval` send by `approvalId` (enforced mode only) | No |

## Setup: Claude Code

Add to `.mcp.json` in your project root. Claude Code passes your shell environment through, so whichever AWS credentials you already use are picked up. Set `AWS_REGION` here regardless: the server reads the region from its own environment (`AWS_REGION` or `AWS_DEFAULT_REGION`), never from your AWS config file, and exits on startup without one.

```json
{
  "mcpServers": {
    "wraps": {
      "command": "npx",
      "args": ["-y", "@wraps.dev/mcp"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

## Setup: Claude Desktop / Cursor / Windsurf

GUI clients inherit nothing from your shell, so any credential settings belong in the same `env` block alongside the region. Claude Desktop config lives at `~/Library/Application Support/Claude/claude_desktop_config.json`; Cursor uses `.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "wraps": {
      "command": "npx",
      "args": ["-y", "@wraps.dev/mcp"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "your-aws-profile"
      }
    }
  }
}
```

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AWS_REGION` | Yes | — | AWS region where your Wraps stack is deployed |
| `WRAPS_HISTORY_TABLE_NAME` | No | `wraps-email-history` | DynamoDB table name for email history |
| `WRAPS_ACCOUNT_ID` | No | auto-detected via STS | Your AWS account ID (skips the STS call if set) |
| `WRAPS_WRITE_ENABLED` | No | `false` | Set to `true` to enable `send_email` |
| `WRAPS_FROM_EMAIL` | No | — | Default `from` address for `send_email` |
| `WRAPS_CONFIGURATION_SET` | No | — | SES configuration set applied to sends (enables open/click tracking) |

## Write Mode

`send_email` is disabled by default. Set `WRAPS_WRITE_ENABLED=true` to enable it. The `from` address must belong to a domain verified in your SES account.

Warning: write mode with no allowlist gives the agent unrestricted send capability to any address your SES account can reach. Set the guardrails below.

## Send Guardrails

| Variable | Default | Description |
|----------|---------|-------------|
| `WRAPS_ALLOWED_RECIPIENTS` | — (no restriction) | Comma-separated exact addresses the agent may send to |
| `WRAPS_ALLOWED_RECIPIENT_DOMAINS` | — (no restriction) | Comma-separated domains; exact match only (subdomains must be listed explicitly) |
| `WRAPS_MAX_RECIPIENTS` | `50` | Maximum recipients per `send_email` call |
| `WRAPS_ALLOW_FROM_OVERRIDE` | `false` | Allow the agent to supply a `from` differing from `WRAPS_FROM_EMAIL` |

A recipient is allowed if it matches either the address list or the domain list.

## Enforced Mode

For agents provisioned via `wraps email agent create`, the agent's AWS credential can only invoke an enforcer Lambda in your account — never SES directly. Kill-switch, recipient allowlist, and hourly/daily caps are decided by that Lambda; local guardrails don't apply. Activated by setting both `WRAPS_AGENT_ID` and `WRAPS_AGENT_ENFORCER_ARN`.

`send_email` returns a structured disposition for policy outcomes: `sent` (with messageId), `pending_approval` (poll `check_send_status` with the returned approvalId), or `blocked` (with a reason). Enforced mode accepts one recipient per send.

## Resources

- npm: https://www.npmjs.com/package/@wraps.dev/mcp
- GitHub: https://github.com/wraps-team/wraps-js/tree/main/packages/mcp
- Agent quickstart: https://wraps.dev/docs/quickstart/email/agents