Connect an agent over MCP

Point an AI agent at Samva's hosted Model Context Protocol server to send and track email as tools.

Samva runs a hosted Model Context Protocol (MCP) server so AI agents can take organization-scoped email actions without you wiring up the REST API.

Endpoint


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

Authentication

The server accepts either credential type, both organization-scoped:

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: an unauthenticated request returns 401 with a WWW-Authenticate: Bearer resource_metadata="…" header pointing at /.well-known/oauth-protected-resource. OAuth-capable clients (such as Cursor) follow that automatically; you only give them the endpoint URL. See API keys and OAuth sessions for the difference.

Configure your client

Client configuration schemas vary, but the generic Streamable HTTP shape with an API key is:

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

Drop the headers and point the client at the same URL; it runs the OAuth flow using the discovery document above.

{
  "mcpServers": {
    "samva": {
      "type": "http",
      "url": "https://mcp.samva.app/mcp"
    }
  }
}

Available tool families

The server publishes these organization-scoped tool families. Use MCP tool discovery for each tool's current input schema.

Family	Tools
Contacts	`samva_contacts_find_or_create`
Messages	`samva_messages_send_email`, `samva_messages_get`, `samva_messages_list_email`, `samva_messages_get_email_status`, `samva_messages_list_email_events`, `samva_messages_list_inbound_email`
Conversations	`samva_conversations_get`
Domains	`samva_email_domains_add`, `samva_email_domains_list`, `samva_email_domains_get`, `samva_email_domains_verify`, `samva_email_domains_check_verification`, `samva_email_domains_get_status`, `samva_email_domains_remove`, `samva_email_domains_enable_receiving`
Senders	`samva_email_senders_add`, `samva_email_senders_list`, `samva_email_senders_get`, `samva_email_senders_check_verification`, `samva_email_senders_remove`
Webhooks	`samva_webhooks_create`, `samva_webhooks_list`, `samva_webhooks_get`, `samva_webhooks_update`, `samva_webhooks_delete`, `samva_webhooks_test`, `samva_webhooks_list_logs`, `samva_webhooks_get_stats`, `samva_webhooks_retry_delivery`, `samva_webhooks_rotate_secret`
Usage and proof	`samva_usage_get`, `samva_email_get_stats`, `samva_email_check_readiness`, `samva_email_get_launch_proof`
Template editor	`samva_templates_open_editor_session`, `samva_templates_connect_editor_session`, `samva_templates_read_source`, `samva_templates_read_model`, `samva_templates_apply_ops`, `samva_templates_write_source`, `samva_templates_render_document`, `samva_templates_check_document`, `samva_templates_send_test_email`, `samva_templates_set_font`, `samva_templates_save_editor_session`
Scheduled email	`samva_scheduled_messages_schedule_email`, `samva_scheduled_messages_list`, `samva_scheduled_messages_get`, `samva_scheduled_messages_cancel`
Campaigns	`samva_campaigns_create`, `samva_campaigns_update`, `samva_campaigns_list`, `samva_campaigns_get`, `samva_campaigns_archive`, `samva_campaigns_schedule_run`, `samva_campaigns_list_runs`, `samva_campaigns_get_run`, `samva_campaigns_control_run`, `samva_campaigns_list_recipients`

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

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`	Template editor session workflow
`samva://guide/scheduling`	Scheduled email and campaign workflows
`samva://reference/sml-agent-contract`	Compact machine-readable SML contract
`samva://reference/sml`	Full SML language reference

Retry a send safely

Pass a stable idempotencyKey to samva_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.

Edit a template safely

Open a session with samva_templates_open_editor_session, or connect to a supplied session id. Then:

Read samva_templates_read_model or samva_templates_read_source.
Call samva_templates_apply_ops with expectedRevision from that read.
Re-read after every mutation before targeting more node ids.
Run samva_templates_check_document and samva_templates_render_document.
Call samva_templates_send_test_email only when you want a real test delivery.
Call samva_templates_save_editor_session when you want to save the draft.

Hosted MCP does not create, find, publish, or unpublish templates. Use the CLI, SDK, REST API, or dashboard for those lifecycle operations.

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

Connect an agent over MCP

Endpoint

Authentication

Configure your client

Available tool families

Resources

Retry a send safely

Edit a template safely

MCP versus Agent Skills

Next steps

Agent Skills

API keys and OAuth sessions

Receive webhooks

On this page