Samva

El servidor MCP alojado de Samva permite a los agentes de IA enviar correos electrónicos, leer respuestas y gestionar plantillas, dominios, campañas y buzones a través de su API de correo.

Ver en samva.dev

Servidor MCP alojado

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

Se instala en Claude Code, Codex, Cursor y más

Documentación

Conecta un agente a través de MCP

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

Samva ejecuta un servidor alojado de Model Context Protocol (MCP). Una clave de API o una conexión OAuth otorgan a un agente herramientas de correo electrónico con alcance organizacional a través de ese servidor.

Para el flujo de trabajo de agentes, consulta API de correo electrónico para agentes de IA.

Para enrutar estas herramientas a través de un catálogo compartido con políticas de aprobación, consulta Conecta Samva a Executor.

Para comenzar desde ChatGPT, consulta Usa el plugin en ChatGPT.

Endpoint [#endpoint]


URL	`https://mcp.samva.dev`
Transporte	HTTP transmisible (sin SSE)
Alcance	Una organización, derivada de tu credencial

Se requiere autenticación [#authentication-is-required]

Conéctate con cualquiera de los dos tipos de credencial. El servidor no trata una cookie del panel de Samva como autenticación MCP.

Modo	Encabezado
Clave de API	`X-API-Key: samva_sk_live_…` o `Authorization: Bearer samva_sk_live_…`
OAuth	`Authorization: Bearer <jwt>`

Para OAuth, el servidor anuncia el descubrimiento según RFC 9728. Una solicitud sin credencial, o con una credencial inválida o caducada, devuelve 401 con un encabezado WWW-Authenticate: Bearer resource_metadata="…" que apunta a /.well-known/oauth-protected-resource. Un token OAuth está vinculado a la única organización que elijas cuando apruebas la conexión. Consulta Autenticación para ambos tipos de credencial.

El descubrimiento de herramientas depende de quien llama. Actualiza o reconecta el cliente MCP después de agregar, eliminar o cambiar una credencial para que no mantenga un catálogo de herramientas obsoleto.

Perfiles de cuentas conectadas [#connected-account-profiles]

profile_get es una herramienta autenticada, de solo lectura y sin argumentos. Su descriptor incluye _meta["openai/profile"]: true. Devuelve id, name y nickname para la membresía del usuario en la organización de la conexión. El ID permanece igual a través de actualizaciones, reconexiones y cambios de nombre para mostrar; el apodo combina los nombres de usuario y organización para la visualización, no para el enrutamiento.

Usa una conexión separada para cada organización. Seleccionar otra conexión no cambia un token existente ni modifica la organización activa del panel. Eliminar la membresía deniega el acceso; volver a agregar al usuario crea un nuevo ID de perfil. Un token existente no caducado puede recuperar el acceso bajo los permisos actuales de esa nueva membresía. Las lecturas de perfil requieren organization:read para claves de API restringidas y no otorgan acceso adicional. La presentación de estos metadatos en el cliente varía según el host.

Usa el plugin en ChatGPT [#use-the-plugin-in-chatgpt]

El plugin publicado de Samva conecta ChatGPT a este servidor alojado. Abre el plugin de Samva en ChatGPT, instálalo y aprueba la conexión para la única organización que elijas. La conexión tiene el mismo acceso con alcance organizacional que cualquier cliente OAuth.

Comienza con una verificación de solo lectura. Ningún mensaje envía correos electrónicos:

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.

Las herramientas que envían, programan, publican o cambian configuraciones son escrituras. Solicítalas solo cuando realmente las necesites. Las herramientas que ChatGPT lista dependen de lo que ese cliente expone, así que usa el descubrimiento de herramientas en lugar de asumir el catálogo completo a continuación. Trabaja con una organización por conexión, como describen los Perfiles de cuentas conectadas. Cualquier otro cliente MCP que admita OAuth usa la configuración a continuación.

Configura tu cliente [#configure-your-client]

Los esquemas de configuración de clientes varían. La forma genérica de HTTP transmisible es:

OAuth

<TabsTrigger value="apikey">
  Clave de API
</TabsTrigger>

Apunta el cliente a la URL MCP alojada y usa su acción de conexión OAuth. El descubrimiento OAuth se publica en el origen MCP.

```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" } } } } ```

Familias de herramientas disponibles [#available-tool-families]

El catálogo autenticado incluye estas familias de herramientas con alcance organizacional. Usa el descubrimiento de herramientas MCP para el esquema de entrada actual de cada herramienta.

Familia	Herramientas
Perfil	`profile_get`
Ayuda de Samva	`ask`, `search_templates`
Contactos	`contacts_find_or_create`
Mensajes	`messages_send_email`, `messages_get`, `messages_list_email`, `messages_get_email_status`, `messages_list_email_events`
Adjuntos	`email_attachments_create_upload`, `email_attachments_complete_upload`
Conversaciones	`conversations_get`
Revisión de correos	`email_review_get_status`, `email_review_reapply`
Seguimiento de correos	`email_tracking_get_defaults`, `email_tracking_update_defaults`, `email_tracking_get_recipient`, `email_tracking_update_recipient`
Dominios	`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`
Remitentes	`email_senders_add`, `email_senders_list`, `email_senders_get`, `email_senders_check_verification`, `email_senders_remove`
Calentamiento de dominios	`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`
Uso y prueba	`usage_get`, `email_get_stats`, `email_check_readiness`, `email_get_launch_proof`
Plantillas	`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`
Marcas	`brands_list`, `brands_get`, `brands_update`
Correo programado	`scheduled_messages_schedule_email`, `scheduled_messages_list`, `scheduled_messages_get`, `scheduled_messages_cancel`, `scheduled_messages_resume`
Campañas	`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`
Comentarios	`feedback_send`

La superficie de MCP incluye totales de uso y lecturas de prueba de correos. El estado de facturación, los derechos y las acciones del portal de facturación están disponibles a través del panel de control, no de MCP.

email_senders_add requiere un idempotencyKey estable. Reutilizar esa clave con entrada idéntica devuelve el remitente original; reutilizarla con entrada diferente genera un conflicto. Los resultados del remitente mantienen el ciclo de vida del proveedor (provisioning, active, deleting o failed) separado de la verificación del buzón (pending, verified o failed).

Recursos [#resources]

El servidor devuelve instrucciones de operación durante la inicialización y publica estos recursos legibles:

URI	Contenido
`samva://guide/email`	Flujo de trabajo de correo transaccional
`samva://guide/template-editor`	Flujo de trabajo de proyecto y espacio de trabajo de plantillas TSX
`samva://guide/scheduling`	Flujos de trabajo de correo programado y campañas
`samva://reference/contract`	Contrato de plantilla legible por máquina: componentes y sus props, las formas del perfil estático, formateadores y códigos de diagnóstico
`samva://reference/sml`	Referencia completa de autoría de plantillas de correo

Reintentar un envío de forma segura [#retry-a-send-safely]

Pasa un idempotencyKey estable a messages_send_email cuando una automatización pueda reintentar la solicitud. Un reintento idéntico devuelve el correo original. Reutilizar la clave con destinatarios, contenido, plantilla o variables cambiados devuelve un conflicto.

La herramienta anuncia la anotación estática de MCP idempotentHint: false porque la clave es opcional. La anotación no cambia para una llamada con clave. Trata un envío como seguro para reintentos solo cuando hayas proporcionado la clave.

Adjuntar un archivo [#attach-a-file]

Los argumentos de las herramientas son texto que escribe el modelo, por lo que los bytes de archivo nunca viajan a través de una llamada de herramienta. Sube cada archivo desde el entorno propio de tu agente:

Llama a email_attachments_create_upload con el filename, contentType y sizeBytes del archivo. Devuelve un mediaId y una instrucción upload.
Envía los bytes exactos del archivo con el método de la instrucción a su url, con cada encabezado que liste, antes de expiresAt. Por ejemplo, curl -X PUT -H "Content-Type: application/pdf" --data-binary @receipt.pdf "$URL".
Llama a email_attachments_complete_upload con el mediaId.
Pasa attachments: [{ "mediaId": "..." }] a messages_send_email o scheduled_messages_schedule_email. La URL de carga es un permiso de escritura de corta duración para ese único archivo, así que trátala como un secreto. Un agente sin shell ni acceso HTTP no puede cargar archivos, y la CLI adjunta archivos locales con --attach. Los adjuntos siguen los límites de adjuntos de correo electrónico.

Editar una plantilla de forma segura [#edit-a-template-safely]

Comienza con templates_list, templates_get o templates_create, luego abre el espacio de trabajo del proyecto con templates_open_workspace. Después:

Llama a templates_diff_workspace cuando necesites los cambios exactos contra la base del espacio de trabajo.
Llama a templates_patch_workspace con expectedRevision y completa los reemplazos o eliminaciones de archivos TSX.
Vuelve a leer después de cada mutación. Reabre con templates_open_workspace para incorporar confirmaciones externas, luego resuelve cualquier conflicto explícito con templates_resolve_workspace_conflict.
Ejecuta templates_check_workspace en la revisión actual y revisa lo que declara el proyecto y cada hallazgo, luego templates_render_fixture con uno de los nombres de fixtures que informó. Llama a templates_snapshot_fixture con el mismo fixture para verlo en anchos de escritorio y móvil, en claro y oscuro.
Llama a templates_save_workspace con la revisión más reciente solo después de una solicitud explícita de guardado.
Usa templates_workspace_history para inspeccionar confirmaciones. templates_restore_workspace prepara un árbol histórico alcanzable como una nueva superposición; no reescribe la rama.
Llama a templates_publish solo después de una solicitud explícita de publicación. La publicación resultante fija el proyecto, la confirmación y la ruta de entrada exactos.

Una plantilla es un archivo TSX en el perfil estático que exporta por defecto defineTemplate, y nada en ella se ejecuta cuando se envía un mensaje. Un proyecto puede contener varias plantillas. Para agregar una, escribe su archivo templates/*.tsx (emails/ también se reconoce) con templates_patch_workspace, luego regístrala con templates_add_entry, usando su id defineTemplate como slug. Lista las plantillas de un proyecto con templates_list y su projectId. Cada plantilla abre el mismo espacio de trabajo compartido y publica por separado. Después de renombrar un archivo, llama a templates_move_entry para que la plantilla conserve su id y publicaciones.

Los archivos del proyecto en el repositorio Git de la plantilla son la fuente de autoría. El HTML y el texto compilados se derivan mediante la vista previa y la publicación. Consulta El bucle del agente para ver cómo las herramientas de plantilla se asignan a la CLI. El MCP alojado no emite credenciales de Git.

Consulta Programar un correo electrónico y Enviar una campaña para secuencias de herramientas orientadas a tareas.

Herramientas de buzón [#mailbox-tools]

El mismo servidor expone herramientas para listar buzones, leer y buscar hilos, responder y revisar correo retenido. Consulta Usar buzones a través de MCP.

MCP versus habilidades de agente [#mcp-versus-agent-skills]

El servidor MCP es ejecución de herramientas en vivo: el agente hace cosas contra Samva. Una Habilidad de agente de Samva es instrucciones: enseña a un agente cómo usar Samva a través del SDK, la CLI y MCP, y qué superficie usar. Se complementan entre sí.