Connect an agent over MCP
Point an authenticated AI agent at Samva's hosted Model Context Protocol server for organization-scoped email tools.
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.
To route these tools through a shared catalog with approval policies, see Connect Samva to Executor.
Endpoint
| URL | https://mcp.samva.dev |
| Transport | Streamable HTTP (no SSE) |
| Scope | One organization, derived from your credential |
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. See
API keys and OAuth sessions for the difference.
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.
Configure your client
Client configuration schemas vary. The generic Streamable HTTP shape is:
Point the client at the hosted MCP URL and use its OAuth connection action. OAuth discovery is published on the MCP origin.
{
"mcpServers": {
"samva": {
"type": "http",
"url": "https://mcp.samva.dev"
}
}
}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 |
|---|---|
| Contacts | contacts_find_or_create |
| Messages | messages_send_email, messages_get, messages_list_email, messages_get_email_status, messages_list_email_events |
| 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_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_get, templates_open_workspace, templates_diff_workspace, templates_patch_workspace, templates_reconcile_workspace, templates_resolve_workspace_conflict, templates_check_workspace, templates_render_fixture, templates_save_workspace, templates_workspace_history, templates_restore_workspace, templates_publish, templates_get_publication |
| 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 |
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
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/sml-agent-contract | Compact executable email contract |
samva://reference/sml | Full Executable email reference |
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.
Edit a template safely
Start with templates_list, templates_get, or templates_create, then open the project workspace
with templates_open_workspace. Then:
- Call
templates_diff_workspacewhen you need the exact changes against the workspace base. - Call
templates_patch_workspacewithexpectedRevisionand complete TSX file replacements or deletions. - Re-read after every mutation. If the Artifact branch advanced, call
templates_reconcile_workspace, then resolve any explicit conflicts withtemplates_resolve_workspace_conflict. - Run
templates_check_workspaceat the current revision and review what the project declares and every finding, thentemplates_render_fixturewith one of the fixture names it reported. - Call
templates_save_workspacewith the latest revision only after an explicit Save request. - Use
templates_workspace_historyto inspect commits.templates_restore_workspacestages a reachable historical tree as a new overlay; it does not rewrite the branch. - Call
templates_publishonly after an explicit Publish request. The resulting publication pins the exact project, commit, and entry path.
The project files in Artifact Git are the authored source. Compiled HTML and text are derived by preview and publication. Hosted MCP does not expose Artifact credentials.
See Schedule an email and Send a campaign for task-oriented tool sequences.
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.