NoticeAPI MCP server

Give an authorized agent the same project-aware capabilities as the REST API: send transactional email, manage templates and domains, operate consent-based marketing, inspect inbound email, update webhooks, and manage projects or keys when its grant permits it.

The hosted endpoint uses stateless MCP Streamable HTTP. A local stdio server ships in the noticeapi package. Both expose the same tool names, input validation, side-effect annotations, and stable NoticeAPI errors.

Hosted Streamable HTTP

POSThttps://mcp.noticeapi.com/mcp

Interactive OAuth (recommended)

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

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

Use local stdio when the agent host does not support authenticated HTTP headers or when you want the API key to remain only in the local process environment.

MCP client configuration

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

Tool groups

Field	Type	Description
`Projects and access`	projects:* / api-keys:write	List, create, update, archive, and issue or revoke grants no broader than the caller.
`Transactional email`	email:send	Send or schedule one message, send 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 key grant 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 grants, 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 the full loop without real mail

agent task

Use NoticeAPI to send a test receipt from [email protected]
to [email protected]. Use Idempotency-Key task-receipt-001,
then fetch the email and summarize its recipient event timeline.

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.