Servidor MCP
Connect es MCP-nativo, con tres herramientas que no cambian nunca: search_docs para descubrir, execute para leer y execute_write para escribir, sobre el catálogo completo.
El servidor vive en https://connect.emisso.ai/mcp: remoto, HTTP, con OAuth 2.1. No hay paquete que
instalar. Anuncia tres herramientas, siempre las mismas, con cualquier catálogo: el catálogo completo
viaja por dentro, sin inflar el contexto de tu agente.
Conéctalo a tu cliente
Claude Code
claude mcp add --transport http connect https://connect.emisso.ai/mcpEl comando solo registra el servidor. Para autorizarlo, abre una sesión de Claude Code, escribe /mcp,
elige connect y luego Authenticate: se abre el consentimiento de Connect en tu navegador.
Claude.ai
El botón abre Claude con Emisso Connect ya escrito:
Claude te va a pedir que confirmes que el conector viene de connect.emisso.ai. Es su chequeo de seguridad, y está bien que lo haga.
A mano: el + del cuadro de mensaje, después Conectores › Agregar conector › Agregar conector
personalizado, o directo en claude.ai/customize/connectors, y pega
https://connect.emisso.ai/mcp.
El navegador abre el consentimiento OAuth de Connect: inicias sesión con tu cuenta y autorizas la
organización.
ChatGPT
Estos pasos son para cuentas personales. En una cuenta de empresa (Business o Enterprise), el modo desarrollador lo habilita un administrador: sigue la ayuda de OpenAI.
1. Activa el modo desarrollador. En ChatGPT: Configuración › Security and login › Developer mode (trae una insignia «ELEVATED RISK»). No hace falta un plan pago: funciona igual en el plan Free.
2. Agrega el servidor MCP. Entra a chatgpt.com/plugins y toca el botón «+»
para abrir «New Plugin»: ponle un nombre, pega https://connect.emisso.ai/mcp en Server URL y deja Authentication
en OAuth, que viene así por defecto. Vas a ver un aviso rojo, «Custom MCP servers introduce risk», con un
casillero obligatorio: sin marcarlo, «Create» queda deshabilitado. Es el chequeo de seguridad de ChatGPT, no
un problema de Connect.
3. Autoriza en tu navegador. Se abre una ventana de Connect: inicias sesión y autorizas la organización.
Cursor
{ "mcpServers": { "connect": { "url": "https://connect.emisso.ai/mcp" } } }Este formato es de Cursor: no sirve tal cual en VS Code, que usa otra clave (servers, no mcpServers) y
exige "type": "http".
Otros clientes
Cualquier cliente compatible con MCP sobre HTTP sirve: usa la dirección https://connect.emisso.ai/mcp.
La autorización es OAuth 2.1 con registro dinámico de clientes y PKCE. Tu agente actúa como tú, dentro de tu organización, y su acceso se corta al instante desde Agentes: la revocación cierra todas sus sesiones y deja de autenticar en la petición siguiente. El detalle del flujo está en Autenticación.
Las tres herramientas
| Herramienta | Qué hace |
|---|---|
search_docs | Qué existe. Sin argumentos devuelve el índice del catálogo agrupado por sistema (los conectados primero), con conectado por sistema y id, una línea de descripción, disponible y puerta por tool, más ahora: la fecha y el mes en curso en hora de Chile, para «este mes» o «el mes pasado». Con { "tool": "sii.rcv.consultar" } devuelve la ficha completa con sus esquemas de entrada y salida y un ejemplo ejecutable. Llámala primero. |
execute | Correr una tool de solo lectura: { tool, params, connectionId }. params es obligatorio ({} si no toma argumentos). connectionId va siempre explícito en todo sistema conectable: la conexión es la empresa y el servidor no la elige. Si hay una sola conexión activa con esa tool, el agente la usa sin preguntar. Si le pasas una tool que escribe, responde validation_error con el llamado correcto ya armado por execute_write. |
execute_write | Correr una tool que escribe: sincronizar, verificar, emitir, anular o reenviar un documento, y crear un enlace de conexión. Acepta { tool, params, connectionId, idempotencyKey? }. También acepta una tool de solo lectura. |
Por qué tres y no una por tool
Un catálogo completo como tools nativas quema la ventana de contexto del agente y cambia de forma con
cada conector nuevo. Un puñado fijo de meta-tools la mantiene constante. Es el mismo argumento con el
que Stripe migró su servidor MCP a stripe_api_search y compañía; Connect llegó a este diseño primero.
Por qué dos puertas de ejecución
execute declara readOnlyHint: true: un cliente MCP puede correrla sin pedir confirmación en cada
llamada. execute_write declara destructiveHint: true y sigue pidiéndola. La ficha de search_docs
nombra la puerta de cada tool en el campo puerta, así que nunca hace falta adivinar.
Clave de idempotencia por operación
execute_write permite enviar idempotencyKey como argumento, fuera de params, sin configurar headers
HTTP en tu cliente MCP. Usa un UUID v4 nuevo, en minúsculas, generado por el cliente para cada operación
distinta. La ficha de search_docs indica cuándo la tool exige esta clave y la incluye en su ejemplo.
{
"tool": "<tool del catálogo>",
"params": {},
"connectionId": "<conn_… de conexiones.estado.consultar>",
"idempotencyKey": "<UUID v4 generado por el cliente para esta operación>"
}Conserva la clave y los argumentos originales para recuperar la misma operación. Si el resultado indica incertidumbre, no reintentes ni generes otra clave: sigue sus instrucciones de reconciliación o soporte. Una clave distinta representa otra operación y no evita una duplicación.
El header HTTP Idempotency-Key sigue funcionando para clientes existentes. Si envías header y argumento,
deben coincidir; de lo contrario recibes validation_error antes de ejecutar la tool. Las tools que no
exigen una clave explícita mantienen su comportamiento cuando la omites. REST conserva el header.
El recorrido que tu agente va a seguir
search_docspara ver los sistemas y qué estáconectado.execute { "tool": "conexiones.estado.consultar", "params": {} }para obtener losconnectionIdy el campodatosListos.executede la tool de negocio con suconnectionId: por ejemplo el RCV de julio.- Si un sistema aparece con
conectado: false, el camino esexecute_write { "tool": "conexiones.enlace.crear", "params": { "sistema": "<código>" } }: el agente crea el enlace y se lo muestra al humano con el dominio visible. La clave la entrega la persona, nunca el agente.
Prompt de arranque
Para darle Connect a un agente con las reglas ya aprendidas:
Enséñale a tu IA a usar Connect
Se abre con el texto ya escrito: lo revisas y lo envías tú. No lleva ninguna clave.
Primero agrega Emisso Connect a tu IA como servidor MCP, con la dirección connect.emisso.ai/mcp. Este texto le enseña a usarlo; no lo instala.
- Abrir en Claudeclaude.ai (abre en una pestaña nueva)
- Abrir en ChatGPTchatgpt.com (abre en una pestaña nueva)
- Abrir en Cursorcursor.com (abre en una pestaña nueva)
Claude te mostrará un aviso de seguridad: lo pone en todo texto que llega por un enlace. Revisa que empiece con «Tienes Emisso Connect (https://connect.emisso.ai/mcp)…» y envíalo.
Lo que le pide a tu IA
- Que parta por
search_docs: el catálogo de lo que puede usar, con la ficha y un ejemplo de cada herramienta. - Que use la empresa correcta: el
connectionIdsiempre explícito; si hay varias conexiones te pregunta cuál, y antes de escribir te confirma la empresa. - Que lea en dos pasos: sincronizar trae los datos y consultar lee lo guardado. Una lista vacía puede ser un período sin sincronizar.
- Que te muestre el enlace cuando falte una conexión, con su dominio a la vista, y que ante un error siga el
suggested_fix.
Tienes Emisso Connect (https://connect.emisso.ai/mcp): el puente a los sistemas chilenos de esta organización (SII, bancos, Previred, indicadores). Reglas:
- Parte siempre por search_docs. Sin argumentos trae el índice de herramientas por sistema, con su puerta (execute para leer, execute_write para escribir): usa solo los ids que aparecen ahí. Con {tool: "<id>"} trae la ficha completa: esquema de argumentos y un ejemplo ejecutable.
- connectionId va siempre explícito en la llamada; sácalo de conexiones.estado.consultar. Considera solo las conexiones activas que tengan la herramienta que necesitas: si queda una, úsala; si quedan varias, pregunta cuál. Antes de escribir (emitir, sincronizar o crear un enlace), confirma la empresa con la persona.
- En el SII, los bancos y Previred, leer son dos pasos: <sistema>.conexion.sincronizar escribe (con execute_write; se encola y vuelve al instante con un jobId, sin datos) y <recurso>.consultar lee lo ya guardado (con execute). Sincronizar requiere un plan activo: sin plan responde 402 subscription_required. Una lista vacía puede ser un período sin sincronizar: revisa datosListos en conexiones.estado.consultar antes de concluir que no hay nada. Notta y los indicadores no se sincronizan: se leen directo con execute.
- Si un sistema aparece con conectado: false, crea un enlace con execute_write y conexiones.enlace.crear, y muéstralo con su dominio completo visible, explicando quién lo pidió y para qué. Nunca lo presentes como un aviso del banco ni del SII.
- Ante un error, sigue el suggested_fix que viene en la respuesta; no reintentes lo que no es reintentable. Si no reconoces el error, reporta el request_id.
Qué hace solo y qué no
| Acción | ¿La hace solo? |
|---|---|
| Descubrir el catálogo, consultar estados, leer datos sincronizados | Sí |
| Disparar una sincronización a pedido | Sí, y sin esperar: la llamada vuelve al instante con el jobId, y el trabajo corre en segundo plano |
| Crear el enlace de conexión | Sí, pero la clave la entrega el humano en la página del enlace |
| Deshabilitar o habilitar una conexión | Solo si la clave o el token tiene conexiones:disable o conexiones:enable. Habilitarla vuelve a sumarla al cobro, y la respuesta dice cuánto |
| Eliminar una conexión | Solo si la clave o el token tiene conexiones:delete y con el nombre exacto de la conexión. Es irreversible: pídelo solo cuando la persona lo decidió |
| Ver o tocar una credencial | Nunca. El vault es inaccesible por diseño, también para el agente |
Compatibilidad
tools/call acepta solo las tres herramientas. Un nombre nativo de antes de las meta-tools
(sii__rcv__consultar, con doble guion bajo) o un id con puntos responde tool_not_found, con la
indicación de usar execute o execute_write. Si tu cliente guardó esos nombres, pásalos como tool
dentro de execute o execute_write: ahí la codificación con doble guion bajo todavía se traduce al id
con puntos, que es la forma canónica que entrega search_docs.
Próximos pasos
- Consultar con Claude o con ChatGPT: una consulta completa, animada, con las llamadas que hace el agente.
- Recursos máquina-legibles: llms.txt, markdown por página y el OpenAPI completo.
- Conecta tu primera empresa: el flujo que tu agente va a iniciar.