Connect an agent over MCP

Samva runs one hosted Model Context Protocol (MCP) server. An API key or OAuth connection gives an agent organization-scoped tools through that server: its mailboxes on email and WhatsApp, sending, templates, domains, and webhooks.

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.

EndpointCopy Anchor Link

Authentication is requiredCopy Anchor Link

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

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 organization and optional namespace you choose when you approve the connection. See Authentication for both credential types.

An OAuth connection lets the client act as you in the organization you select, including direct API access. Choose a namespace after the organization to confine the connection to that namespace. It then has your role's grants capped to namespace-aware resources, just like a namespace API key: lists show only its resources, reads outside it return 404, and organization-wide endpoints such as webhook management return 403. Shared templates and read-only brands remain available.

For an unrestricted member, leaving Whole organization selected gives the connection their full organization role. A restricted member stays inside their membership namespace, including when connecting a client. OAuth scopes do not narrow that role. Approve only clients you trust with the access you select. Check the redirect host and the application publisher host on the consent screen; an application chooses its own display name. Removing your organization membership stops access. Revoking a namespace connection's consent or deleting its namespace also stops its access. For a whole-organization connection, disconnecting a client does not immediately invalidate an access token it already holds; that token can remain usable until it expires.

MCP clients register through an HTTPS client metadata document (CIMD). Session-based client creation and dynamic client registration are disabled. A temporary authorization-backend failure returns 503; reconnecting does not repair an outage. A permission denial returns 403 with a Bearer error="insufficient_scope" challenge. Organization restrictions still apply, and requesting consent again cannot override them.

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 profilesCopy Anchor Link

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 ChatGPTCopy Anchor Link

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 clientCopy Anchor Link

Client configuration schemas vary. Step-by-step guides cover Claude Code, Codex, Cursor, and opencode.

Hand the setup to your agentCopy Anchor Link

In a coding agent, paste this prompt. The agent reads this page as Markdown, follows the guide for its own client, and stops when you need to approve the connection.

Read https://samva.dev/docs/developers/mcp.md and connect yourself to the Samva MCP server at https://mcp.samva.dev with OAuth. Follow the setup guide for the client you are running in, run the commands yourself, and tell me when I need to sign in.

Configure it yourselfCopy Anchor Link

For a client without a guide, the generic Streamable HTTP shape is:

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

Available tool familiesCopy Anchor Link

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

ask retrieves cited passages from Samva's public documentation, guides, and other content. Its response contains passages, each with title, url, heading, and text. Your model uses those passages to write the answer. Pass scope as a Samva route or URL to search one page.

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).

ResourcesCopy Anchor Link

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

Retry a send safelyCopy Anchor Link

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 fileCopy Anchor Link

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.

Start from a briefCopy Anchor Link

templates_suggest takes a brief and returns the three gallery designs that fit it best, each with a galleryTemplateId and the reason it fits, plus a recreation match when the brief names a company. templates_create_from_brief creates a template project from the best match, or from the galleryTemplateId you pass, and returns the template, the design it started from, the alternatives, and ask, the request that adapts the design to the brief. A new email starts from the gallery design that fits the brief, not from a blank project.

A brief that names a company starts from Samva's recreation of that company's email. If Samva has only a different kind of email from that company, the project starts from it for the look. If there is no recreation, it starts from the closest design and says so.

Agents read the design guidance with templates_design_guide before they edit. The same operations are POST /v1/templates/suggestions and POST /v1/templates/from-brief in the API and samva templates suggest and samva templates from-brief in the CLI.

Match a websiteCopy Anchor Link

templates_create_from_website takes a public website address and creates a template project from the starter. It returns the template and project ids, the site Samva checked, and ask, the request for the dashboard editor's assistant to match the site. The assistant proposes a brand that changes nothing until the customer applies it. A site that is not public, does not answer, or refuses automated visits fails with a message that names the cause. See Match your website.

Edit a template safelyCopy Anchor Link

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. If the source cannot build, the call fails with TemplateSourceError and its diagnostics; fix the source with templates_patch_workspace, then save again. templates_publish, templates_restore_workspace, and open can fail the same way.
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.

templates_update changes a template's name, description, and category, and sets its sending defaults: fromDefault, replyToDefault, and trackingDefault. Send only the fields to change; a null clears a default so the template inherits again. See Engagement tracking for how the tracking default combines with the domain and organization defaults.

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 toolsCopy Anchor Link

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

For WhatsApp, whatsapp_setup_links_* creates and manages the links that let your customers connect their own numbers (Onboard your customers' numbers).

MCP versus Agent SkillsCopy Anchor Link

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 stepsCopy Anchor Link