Samva

npx add-mcp 'https://mcp.samva.dev'

Connect an agent over MCP

URL: https://samva.dev/docs/developers/mcp

Samva runs one hosted Model Context Protocol (MCP) server. An API key or OAuth connection gives an agent organization-scoped email tools through that server.

For the agent workflow, see Email API for AI agents.

To route these tools through a shared catalog with approval policies, see Connect Samva to Executor.

To start from ChatGPT, see Use the plugin in ChatGPT.

Endpoint [#endpoint]

URL	https://mcp.samva.dev
Transport	Streamable HTTP (no SSE)
Scope	One organization, derived from your credential

Authentication is required [#authentication-is-required]

Connect with either credential type. The server does not treat a Samva dashboard cookie as MCP authentication.

Mode	Header
API key	X-API-Key: samva_sk_live_… or Authorization: Bearer samva_sk_live_…
OAuth	Authorization: Bearer <jwt>

For OAuth, the server advertises discovery per RFC 9728. A request without a credential, or with an invalid or expired credential, returns 401 with a WWW-Authenticate: Bearer resource_metadata="…" header pointing at /.well-known/oauth-protected-resource. An OAuth token is bound to the one organization you choose when you approve the connection. See Authentication for both credential types.

Tool discovery is caller-dependent. Refresh or reconnect the MCP client after adding, removing, or changing a credential so it does not keep a stale tool catalog.

Connected account profiles [#connected-account-profiles]

profile_get is an authenticated, read-only tool with no arguments. Its descriptor includes _meta["openai/profile"]: true. It returns id, name, and nickname for the user’s membership in the connection’s organization. The ID stays the same across refresh, reconnect, and display-name changes; the nickname combines the user and organization names for display, not routing.

Use a separate connection for each organization. Selecting another connection does not switch an existing token or change the dashboard’s active organization. Removing membership denies access; re-adding the user creates a new profile ID. An unexpired existing token can regain access under that new membership’s current permissions. Profile reads require organization:read for restricted API keys and do not grant additional access. Client presentation of this metadata varies by host.

Use the plugin in ChatGPT [#use-the-plugin-in-chatgpt]

The published Samva plugin connects ChatGPT to this hosted server. Open the Samva plugin in ChatGPT, install it, and approve the connection for the one organization you choose. The connection has the same organization-scoped access as any OAuth client.

Start with a read-only check. Neither prompt sends email:

• Using Samva, check whether this organization is ready to send email and list what is left to set up.
• Using Samva, show the status of my most recent email.

Tools that send, schedule, publish, or change settings are writes. Ask for them only when you mean them. The tools ChatGPT lists depend on what that client exposes, so use tool discovery instead of assuming the full catalog below. Work with one organization per connection, as Connected account profiles describes. Any other MCP client that supports OAuth uses the setup below.

Configure your client [#configure-your-client]

Client configuration schemas vary. The generic Streamable HTTP shape is:

OAuth

<TabsTrigger value="apikey">
  API key
</TabsTrigger>

Point the client at the hosted MCP URL and use its OAuth connection action. OAuth discovery is published on the MCP origin.

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

```json { "mcpServers": { "samva": { "type": "http", "url": "https://mcp.samva.dev", "headers": { "X-API-Key": "samva_sk_live_your_api_key" } } } } ```

Available tool families [#available-tool-families]

The authenticated catalog includes these organization-scoped tool families. Use MCP tool discovery for each tool's current input schema.

Family	Tools
Profile	profile_get
Samva help	ask, search_templates
Contacts	contacts_find_or_create
Messages	messages_send_email, messages_get, messages_list_email, messages_get_email_status, messages_list_email_events
Attachments	email_attachments_create_upload, email_attachments_complete_upload
Conversations	conversations_get
Email review	email_review_get_status, email_review_reapply
Email tracking	email_tracking_get_defaults, email_tracking_update_defaults, email_tracking_get_recipient, email_tracking_update_recipient
Domains	email_domains_add, email_domains_list, email_domains_get, email_domains_verify, email_domains_check_verification, email_domains_get_status, email_domains_rotate_dkim, email_domains_remove, email_domains_enable_receiving, email_domains_enable_custom_tracking, email_domains_get_custom_tracking, email_domains_recheck_custom_tracking, email_domains_disable_custom_tracking
Senders	email_senders_add, email_senders_list, email_senders_get, email_senders_check_verification, email_senders_remove
Domain warming	email_domains_warming_get, email_domains_warming_start, email_domains_warming_update_policy, email_domains_warming_pause, email_domains_warming_resume
Webhooks	webhooks_create, webhooks_list, webhooks_get, webhooks_update, webhooks_delete, webhooks_test, webhooks_list_logs, webhooks_get_stats, webhooks_retry_delivery, webhooks_rotate_secret
Usage and proof	usage_get, email_get_stats, email_check_readiness, email_get_launch_proof
Templates	templates_create, templates_list, templates_add_entry, templates_move_entry, templates_get, templates_open_workspace, templates_diff_workspace, templates_patch_workspace, templates_resolve_workspace_conflict, templates_check_workspace, templates_render_fixture, templates_snapshot_fixture, templates_save_workspace, templates_workspace_history, templates_restore_workspace, templates_publish, templates_get_publication
Brands	brands_list, brands_get, brands_update
Scheduled email	scheduled_messages_schedule_email, scheduled_messages_list, scheduled_messages_get, scheduled_messages_cancel, scheduled_messages_resume
Campaigns	campaigns_create, campaigns_update, campaigns_list, campaigns_get, campaigns_archive, campaigns_schedule_run, campaigns_list_runs, campaigns_get_run, campaigns_control_run, campaigns_list_recipients
Feedback	feedback_send

The MCP surface includes usage totals and email proof reads. Billing status, entitlements, and billing portal actions are available through the dashboard, not MCP.

email_senders_add requires a stable idempotencyKey. Reusing that key with identical input returns the original sender; reusing it with different input conflicts. Sender results keep provider lifecycle (provisioning, active, deleting, or failed) separate from mailbox verification (pending, verified, or failed).

Resources [#resources]

The server returns operating instructions during initialization and publishes these readable resources:

URI	Contents
samva://guide/email	Transactional email workflow
samva://guide/template-editor	TSX template-project and workspace workflow
samva://guide/scheduling	Scheduled email and campaign workflows
samva://reference/contract	Machine-readable template contract: components and their props, the forms of the static profile, formatters, and diagnostic codes
samva://reference/sml	Full email template authoring reference

Retry a send safely [#retry-a-send-safely]

Pass a stable idempotencyKey to messages_send_email when an automation might retry the request. An identical retry returns the original email. Reusing the key with changed recipients, content, template, or variables returns a conflict.

The tool advertises the static MCP annotation idempotentHint: false because the key is optional. The annotation does not change for a keyed call. Treat a send as retry-safe only when you supplied the key.

Attach a file [#attach-a-file]

Tool arguments are text the model writes, so file bytes never travel through a tool call. Upload each file from your agent's own environment instead:

1. Call email_attachments_create_upload with the file's filename, contentType, and sizeBytes. It returns a mediaId and an upload instruction.
2. Send the file's exact bytes with the instruction's method to its url, with every header it lists, before expiresAt. For example, curl -X PUT -H "Content-Type: application/pdf" --data-binary @receipt.pdf "$URL".
3. Call email_attachments_complete_upload with the mediaId.
4. Pass attachments: [{ "mediaId": "..." }] to messages_send_email or scheduled_messages_schedule_email.

The upload URL is a short-lived write permission for that one file, so treat it like a secret. An agent without a shell or HTTP access cannot upload, and the CLI attaches local files with --attach. Attachments follow the email attachment limits.

Edit a template safely [#edit-a-template-safely]

Start with templates_list, templates_get, or templates_create, then open the project workspace with templates_open_workspace. Then:

1. Call templates_diff_workspace when you need the exact changes against the workspace base.
2. Call templates_patch_workspace with expectedRevision and complete TSX file replacements or deletions.
3. Re-read after every mutation. Reopen with templates_open_workspace to pull outside commits, then resolve any explicit conflicts with templates_resolve_workspace_conflict.
4. Run templates_check_workspace at the current revision and review what the project declares and every finding, then templates_render_fixture with one of the fixture names it reported. Call templates_snapshot_fixture with the same fixture to see it at desktop and mobile widths, in light and dark.
5. Call templates_save_workspace with the latest revision only after an explicit Save request.
6. Use templates_workspace_history to inspect commits. templates_restore_workspace stages a reachable historical tree as a new overlay; it does not rewrite the branch.
7. Call templates_publish only after an explicit Publish request. The resulting publication pins the exact project, commit, and entry path.

A template is one TSX file in the static profile that default-exports defineTemplate, and nothing in it runs when a message is sent. A project can hold several templates. To add one, write its templates/*.tsx file (emails/ is also recognized) with templates_patch_workspace, then register it with templates_add_entry, using its defineTemplate id as the slug. List a project's templates with templates_list and its projectId. Each template opens the same shared workspace and publishes separately. After renaming a file, call templates_move_entry so the template keeps its id and publications.

The project files in the template's Git repository are the authored source. Compiled HTML and text are derived by preview and publication. See The agent loop for how the template tools map to the CLI. Hosted MCP does not issue Git credentials.

See Schedule an email and Send a campaign for task-oriented tool sequences.

Mailbox tools [#mailbox-tools]

The same server exposes tools to list mailboxes, read and search threads, reply, and review held mail. See Use mailboxes over MCP.

MCP versus Agent Skills [#mcp-versus-agent-skills]

The MCP server is live tool execution: the agent does things against Samva. A Samva Agent Skill is instructions: it teaches an agent how to use Samva across the SDK, CLI, and MCP, and which surface to reach for. They complement each other.

Next steps [#next-steps]