MCP email setup for coding agents

Connect NoticeAPI to your coding agent. Send a simulator email and inspect the result before enabling production email.

The hosted endpoint uses stateless MCP Streamable HTTP. The local stdio server is part of the unpublished noticeapi 0.2.0 preview. Both expose the same tool names, input validation, side-effect annotations, and stable NoticeAPI errors.

1. Connect hosted MCP

Add this URL to a client that supports Streamable HTTP and OAuth. Choose your application project and grant email:send. Add projects:read if your agent needs to list projects.

POSThttps://mcp.noticeapi.com/mcp

Hosted connection settings

{
  "mcpServers": {
    "noticeapi": {
      "type": "http",
      "url": "https://mcp.noticeapi.com/mcp"
    }
  }
}

The JSON shows connection settings. Client configuration formats differ. Add the URL through your client's remote MCP setup.

2. Send and inspect a simulator email

Agent task

Use NoticeAPI to send a test receipt from demo@sandbox.noticeapi.com
to delivered@simulator.noticeapi.com. Use Idempotency-Key task-receipt-001,
then fetch the email and summarize its recipient event timeline.

Call send_email, then call get_email with the returned ID. Confirm deliveryStatus: delivered and a delivered recipient event.

The simulator does not contact a mailbox. For production, verify your email address and sending domain, then add a card. See the agent guide for the full setup path.

OAuth and headless connection reference

An OAuth-capable client discovers NoticeAPI from the protected-resource metadata, opens a browser for sign-in, and asks you to choose capabilities plus project access. The flow uses authorization code with S256 PKCE, exact callback matching, resource-bound one-hour access tokens, and no client secret in the browser.

For CI or another headless agent, pass a scoped ntc_… API key explicitly instead. OAuth grants and API keys can both be revoked from NoticeAPI; consent, unsubscribe, suppression, quota, and deliverability rules remain enforced either way.

Headless bearer-key configuration

{
  "mcpServers": {
    "noticeapi": {
      "type": "http",
      "url": "https://mcp.noticeapi.com/mcp",
      "headers": { "Authorization": "Bearer $NOTICEAPI_API_KEY" }
    }
  }
}

Discovery is public at https://mcp.noticeapi.com/.well-known/oauth-protected-resource/mcp. The authorization server publishes its endpoints and PKCE support at https://www.noticeapi.com/.well-known/oauth-authorization-server.

Choose a project

Project-bound keys need no extra configuration. A workspace key can set X-NoticeAPI-Project-ID for the connection, or pass projectId to an individual project-scoped tool. If the key can access several projects and neither value is supplied, the API returns project_required instead of guessing.

workspace key

{
  "url": "https://mcp.noticeapi.com/mcp",
  "headers": {
    "Authorization": "Bearer $NOTICEAPI_API_KEY",
    "X-NoticeAPI-Project-ID": "project_123"
  }
}

Local stdio: unpublished SDK 0.2.0 preview

The following configuration requires SDK 0.2.0, which is not available on npm yet. Use hosted MCP with the current release.

Preview configuration, requires the unpublished package

{
  "mcpServers": {
    "noticeapi": {
      "command": "npx",
      "args": ["-y", "-p", "noticeapi@0.2.0", "noticeapi-mcp"],
      "env": {
        "NOTICEAPI_API_KEY": "ntc_xxxxxxxxxxxxxxxxxxxx",
        "NOTICEAPI_PROJECT_ID": "project_123"
      }
    }
  }
}

Tool reference

Field	Type	Description
`Projects and access`	projects:* / api-keys:write	List, create, update, archive, and issue or revoke API keys no broader than the caller.
`Transactional email`	email:send	Send or schedule one message, queue immediate batches, cancel/reschedule scheduled messages, and read recipient event timelines.
`Domains`	domains:read / domains:write	Create, inspect, verify, and remove sending domains.
`Templates`	templates:write	Create, inspect, update, and remove stored templates.
`Marketing`	audiences / broadcasts / automations	Operate opted-in contacts, broadcasts, and lifecycle sequences with unsubscribe enforcement intact.
`Receiving`	receiving:read / receiving:write	Manage API receiving domains and read inbound messages. NoticeAPI is not a mailbox product.
`Operations`	webhooks / suppressions	Manage signed event endpoints and recipient suppression state.

Authority and safety

The credential's scope is the authority boundary. NoticeAPI does not add a separate confirmation screen in front of MCP calls, although an MCP client may choose to confirm a tool marked as side-effecting or destructive. The platform still enforces project and domain access, consent, unsubscribe behavior, suppressions, quotas, deliverability pauses, and the acceptable-use policy.

Send calls are marked side-effecting; delete, revoke, and archive tools are marked destructive. Use an Idempotency-Key for transactional sends so a client retry cannot double-send.

Test other outcomes

Simulator recipients exercise the send, status, event, webhook, and suppression pipeline without contacting a real mailbox. See the testing guide before production automation.

REST and generated clients

Every MCP tool maps to shipped REST behavior. Use the canonical OpenAPI 3.1 document, the REST reference, or the Node SDK when a direct integration is a better fit.