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 narrow, organization-scoped actions — send email, look up messages and conversations, manage webhooks, read usage — without you wiring up the REST API by hand.
Email first. The MCP server exposes email and shared reads only. SMS, WhatsApp, and voice tools are not available.
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: sk_sm_… or Authorization: Bearer sk_… |
| 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": "sk_sm_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 tools
The complete, fixed tool set:
| Tool | Does |
|---|---|
samva_contacts_find_or_create | Find or create a contact by email, phone, WhatsApp, or external id |
samva_messages_send_email | Send transactional email to one or more recipients |
samva_messages_get | Fetch a message by id with delivery status |
samva_conversations_get | Fetch a conversation by id |
samva_webhooks_list | List the organization's webhook endpoints |
samva_webhooks_test | Send a synthetic test event to a webhook endpoint |
samva_usage_get | Read the organization's usage for a period |
Once connected, the server is self-describing: it returns usage instructions on initialize and
exposes a readable samva://guide/email resource with the full email workflow — so a connected
agent needs no extra setup to use it correctly.
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.