MCP Server

Conecta Claude, ChatGPT, Cursor, VS Code o cualquier cliente MCP directamente a tu espacio de trabajo.

Esta es la forma estratégica de usar SOIS: trae tu propio agente. Tu espacio de trabajo de Sois AI es un servidor MCP completo, por lo que el agente de IA que ya usas se conecta y razona sobre las herramientas de tu espacio de trabajo directamente. Cada vez más, las personas nunca inician sesión en la consola de SOIS. Le dicen a su propio Claude, ChatGPT, Cursor o Gemini lo que necesitan, y este opera SOIS en su nombre a través de MCP. La consola se convierte en un lugar para ver y administrar la actividad del agente, no en la forma principal de hacer el trabajo.

Cualquier cliente que hable el Model Context Protocol puede conectarse y usar las herramientas de tu espacio de trabajo: buscar contactos, crear tareas, enviar correos, administrar documentos y más, sin escribir una sola integración. Como tu propio agente hace el razonamiento, SOIS no gasta IA en tu nombre.

Un solo endpoint. Protocolo estándar. Todas las herramientas que tu cuenta puede usar, disponibles para cualquier cliente compatible.

La única URL

Tu espacio de trabajo expone un solo endpoint MCP:

https://<your-workspace>.sois.ai/api/mcp

El servidor se identifica con la marca de tu espacio de trabajo (por ejemplo "Acme"), por lo que aparece con tu propio nombre en el cliente. Todo lo demás depende de esa única URL.

Hay dos formas de autenticarte. OAuth es la ruta recomendada y es la que usan los conectores integrados en Claude y ChatGPT: pegas la URL, apruebas una vez y no hay token que copiar o rotar manualmente. Un token Bearer más una clave API también es compatible para scripts, servidores y clientes que no usan OAuth.

Opción A: OAuth 2.1 (recomendada, nada que pegar)

Los conectores MCP modernos descubren y completan todo el inicio de sesión por ti. Solo proporcionas la URL.

1. En tu cliente (por ejemplo Claude o ChatGPT), agrega un conector personalizado y pega tu URL MCP: https://<your-workspace>.sois.ai/api/mcp

2. El cliente llama al endpoint sin token y recibe un 401 con un desafío de descubrimiento:

WWW-Authenticate: Bearer resource_metadata="https://<your-workspace>.sois.ai/.well-known/oauth-protected-resource"

3. El cliente lee esos metadatos, encuentra el servidor de autorización de tu espacio de trabajo, se registra automáticamente (Dynamic Client Registration) y abre la pantalla de inicio de sesión y consentimiento.

4. Apruebas la conexión en tu cuenta de SOIS. El cliente recibe un token mediante PKCE (con un token de actualización rotativo) y comienza a trabajar. Nunca se copia un token manualmente.

Por qué es seguro. El servidor de autorización es el dominio de tu propio espacio de trabajo, por lo que los tokens están limitados al inquilino y nunca salen de tu red. La autorización es tu rol: un token otorgado nunca puede hacer más de lo que tú puedes, porque cada llamada a una herramienta se verifica por permisos en el momento de la ejecución. Las cadenas de alcance son amplias a propósito; el límite real son tus permisos por usuario.

Lo que anuncia el servidor de autorización:

Propiedad	Valor
Authorization endpoint	`/oauth/authorize`
Token endpoint	`/oauth/token`
Registration endpoint	`/oauth/register` (Dynamic Client Registration)
Grant types	`authorization_code`, `refresh_token`
PKCE	requerido (`S256`)
Scopes	`mcp`, `mcp:read`, `mcp:write`, `offline_access`

Normalmente no llamas a estos endpoints tú mismo; un cliente MCP compatible recorre el flujo automáticamente una vez que tiene la URL.

Opción B: Token Bearer + clave API (directa o del lado del servidor)

Para scripts, servidores o cualquier cliente que no implemente OAuth. Generas dos credenciales y las envías como encabezados en cada solicitud.

1. Abre Configuración > Conecta tu agente en tu espacio de trabajo de Sois AI.

2. Elige tu cliente (Claude Desktop, Cursor, VS Code o Generic) y haz clic en Generar credenciales para obtener un token Bearer, una clave API y un fragmento de configuración listo para usar.

3. Pega la configuración en tu cliente.

{
  "mcpServers": {
    "sois-workspace": {
      "url": "https://<your-workspace>.sois.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Cursor usa la misma estructura en .cursor/mcp.json; VS Code la anida bajo "mcp": { "servers": { ... } } con "type": "http".

Encabezado	Valor	Propósito
`Authorization`	`Bearer <token>`	Identidad (token Sanctum, caducidad de 90 días)
`X-Api-Key`	`sois_...`	Seguimiento de presupuesto y uso

Dos credenciales porque la identidad y el gasto están separados: un token demuestra quién eres, la clave controla y mide el costo, y cualquiera de las dos por sí sola es inútil. (Los tokens OAuth llevan su autorización de otra forma, por lo que un conector de la Opción A no necesita el encabezado X-Api-Key.)

Genera el par mediante programación cuando automatizas la incorporación:

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/quick-setup" \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "generic"}'

Endpoints de descubrimiento

Un cliente puede aprender todo lo que necesita de tres documentos públicos en la raíz de tu espacio de trabajo:

Endpoint	Propósito
`/.well-known/mcp.json`	Tarjeta del servidor: nombre, versión, versión del protocolo y ubicaciones de los metadatos OAuth
`/.well-known/oauth-protected-resource`	RFC 9728: qué servidor de autorización protege este recurso
`/.well-known/oauth-authorization-server`	RFC 8414: los endpoints de autorización, token y registro, concesiones y método PKCE

La tarjeta del servidor informa authentication.type como oauth2 y enlaza a los dos documentos OAuth, que es cómo un conector sabe que debe iniciar el flujo de la Opción A.

Detalles del protocolo

El endpoint habla Streamable HTTP con JSON-RPC 2.0 (versión de la especificación 2025-06-18).

Ciclo de vida de la sesión

Paso	Solicitud	Notas
Inicializar	`POST /api/mcp` método `initialize`	Negocia capacidades; la respuesta lleva un encabezado `Mcp-Session-Id`
Listar herramientas	`POST /api/mcp` método `tools/list`	Devuelve todas las herramientas que tu cuenta puede usar
Llamar a una herramienta	`POST /api/mcp` método `tools/call`	`params.name` + `params.arguments`
Mantener activa	`GET /api/mcp` con `Mcp-Session-Id`	Abre un flujo SSE para mensajes del servidor al cliente
Finalizar	`DELETE /api/mcp` con `Mcp-Session-Id`	Termina la sesión

Incluye el Mcp-Session-Id de la respuesta de inicialización en cada solicitud posterior.

Métodos compatibles

Método	Descripción
`initialize`	Inicia una sesión, negocia capacidades
`ping`	Comprobación de estado
`tools/list`	Lista las herramientas disponibles con esquemas
`tools/call`	Ejecuta una herramienta por nombre con argumentos
`notifications/initialized`	El cliente confirma la inicialización (sin respuesta)
`notifications/cancelled`	El cliente cancela una solicitud pendiente (sin respuesta)

Qué herramientas están disponibles

tools/list devuelve todo lo que puedes hacer dentro de Sois AI, filtrado según tus permisos:

Contactos: buscar, crear, actualizar, resumir
Tareas: crear, asignar, actualizar estado, buscar
Calendario: listar, crear, actualizar eventos, comprobar disponibilidad
Documentos: buscar, crear, actualizar contenido
Archivos: explorar, subir, descargar
Bandeja de entrada: leer, redactar, enviar
Departamentos y equipo: listar y administrar (administrador)
Aplicaciones instaladas: todas las herramientas añadidas por las extensiones que tienes instaladas (CRM, facturación, almacén, entidades personalizadas, etc.)

La lista exacta depende del rol del usuario autenticado y de las aplicaciones instaladas. Las herramientas están filtradas por permisos y fallan de forma cerrada, por lo que una conexión nunca puede llamar a algo que el usuario no tenga permitido usar.

El constructor de aplicaciones se ejecuta sobre este mismo endpoint

No hay un servidor MCP separado para crear aplicaciones. Las herramientas del constructor de extensiones forman parte del mismo servidor MCP del espacio de trabajo y aparecen en el mismo tools/list, con una condición: están restringidas a administradores, por lo que solo aparecen para cuentas con capacidad de constructor. Si tu cuenta puede crear aplicaciones, tu lista de herramientas también incluye:

getExtensionRules, getExtensionFrameSpec (cómo debe verse una aplicación)
createExtensionProject, listExtensionProjects, getExtensionStatus
validateExtensionBundle, uploadExtensionBundle

Por lo tanto, crear una aplicación es el mismo acto que todo lo demás: conectas tu agente a tu espacio de trabajo una sola vez y, si eres constructor, puede generar, validar y publicar una aplicación junto con la gestión de tu negocio, todo a través del único endpoint /api/mcp. Consulta Crea una app para ver el flujo de trabajo.

(No debe confundirse con el conector público de solo lectura del contexto de compilación que un operador puede añadir para anunciar las capacidades de una red; ese es un endpoint separado y no autenticado en el dominio de la red, no el servidor MCP de tu espacio de trabajo.)

Presupuesto, límites y errores

Qué	Valor
Límite de tasa	120 solicitudes/minuto
Costo de llamada a herramienta	medido en créditos de IA
Presupuesto	por clave API (Opción B) o por espacio de trabajo; tú defines el límite
Caducidad del token	90 días (token Sanctum de la Opción B); los tokens OAuth se actualizan automáticamente

Se aplican los errores JSON-RPC estándar, además de algunos códigos específicos:

Código	Significado
`-32001`	No autorizado o sesión caducada (los conectores de la Opción A reciben el desafío OAuth aquí)
`-32002`	Créditos de IA insuficientes
`-32003`	Herramienta no permitida para esta cuenta
`-32004`	Límite de presupuesto alcanzado

Prueba tu conexión

curl -X POST "https://<your-workspace>.sois.ai/api/mcp/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: YOUR_API_KEY"

Devuelve si las credenciales funcionan y cuántas herramientas están visibles para ellas.

Traer tu propio agente es la ruta estratégica. El servidor MCP permite que tu propio cliente de IA razone directamente sobre tus herramientas de SOIS, por lo que SOIS no gasta IA en tu nombre. La Chat Agent Gateway es el punto de entrada para quienes llaman que no tienen agente: mensajes en lenguaje natural por HTTP, donde el propio agente de SOIS hace el razonamiento. Usa el que se adapte a quien llama, o ambos.

¿Quieres conectar Sois a servidores MCP externos en su lugar? Consulta la MCP Gateway para conexiones salientes.