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, de modo que el agente de IA que ya usas se conecta y razona directamente sobre las herramientas de tu espacio de trabajo. Cada vez más, la gente nunca inicia sesión en la consola de SOIS. Le dice a su propio Claude, ChatGPT, Cursor o Gemini lo que necesita, y este opera SOIS en su nombre a través de MCP. La consola se convierte en un lugar para ver y gestionar 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, gestionar documentos y más, sin escribir ni una sola integración. Como tu propio agente hace el razonamiento, SOIS no gasta IA en tu nombre.

Un solo punto de conexión. 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 único punto de conexión MCP:

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

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

Hay dos formas de autenticarse. OAuth es la vía recomendada y es la que usan los conectores integrados en Claude y ChatGPT: pegas la URL, apruebas una vez y no hay ningún token que copiar o rotar manualmente. También se admite un token Bearer más clave de API para scripts, servidores y clientes que no hacen 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), añade un conector personalizado y pega tu URL MCP: https://<your-workspace>.sois.ai/api/mcp

2. El cliente llama al punto de conexión 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 refresco rotatorio) y empieza a trabajar. Nunca se copia ningún token a mano.

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

Lo que anuncia el servidor de autorización:

Property	Value
Authorization endpoint	`/oauth/authorize`
Token endpoint	`/oauth/token`
Registration endpoint	`/oauth/register` (Dynamic Client Registration)
Grant types	`authorization_code`, `refresh_token`
PKCE	required (`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 de 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 cabeceras en cada solicitud.

1. Abre Ajustes > 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 de 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".

Header	Value	Purpose
`Authorization`	`Bearer <token>`	Identity (Sanctum token, 90-day expiry)
`X-Api-Key`	`sois_...`	Budget and usage tracking

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

Genera el par mediante programación cuando automatices 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"}'

Puntos de conexión 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	Purpose
`/.well-known/mcp.json`	Server card: name, version, protocol version, and the OAuth metadata locations
`/.well-known/oauth-protected-resource`	RFC 9728: which authorization server protects this resource
`/.well-known/oauth-authorization-server`	RFC 8414: the authorize, token, and registration endpoints, grants, and PKCE method

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 punto de conexión habla Streamable HTTP con JSON-RPC 2.0 (versión de la especificación 2025-06-18).

Ciclo de vida de la sesión

Step	Request	Notes
Initialize	`POST /api/mcp` method `initialize`	Negotiates capabilities; the response carries an `Mcp-Session-Id` header
List tools	`POST /api/mcp` method `tools/list`	Returns every tool your account is allowed to use
Call a tool	`POST /api/mcp` method `tools/call`	`params.name` + `params.arguments`
Keep-alive	`GET /api/mcp` with `Mcp-Session-Id`	Opens an SSE stream for server-to-client messages
Teardown	`DELETE /api/mcp` with `Mcp-Session-Id`	Ends the session

Incluye el Mcp-Session-Id de la respuesta de inicialización en todas las solicitudes posteriores.

Métodos admitidos

Method	Description
`initialize`	Start a session, negotiate capabilities
`ping`	Health check
`tools/list`	List available tools with schemas
`tools/call`	Execute a tool by name with arguments
`notifications/initialized`	Client confirms initialization (no response)
`notifications/cancelled`	Client cancels a pending request (no response)

Qué herramientas están disponibles

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

Contacts: search, create, update, summarise
Tasks: create, assign, update status, search
Calendar: list, create, update events, check availability
Documents: search, create, update content
Files: browse, upload, download
Inbox: read, compose, send
Departments and team: list and manage (admin)
Installed apps: every tool added by the extensions you have installed (CRM, invoicing, warehouse, custom entities, and so on)

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

El constructor de aplicaciones funciona sobre este mismo punto de conexión

No hay un servidor MCP separado para crear aplicaciones. Las herramientas del constructor de extensiones se envían como 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, de modo que solo aparecen para las cuentas con capacidad de constructor. Si tu cuenta puede crear aplicaciones, tu lista de herramientas también incluye:

getExtensionRules, getExtensionFrameSpec (what an app must look like)
createExtensionProject, listExtensionProjects, getExtensionStatus
validateExtensionBundle, uploadExtensionBundle

Por 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, este puede generar el andamiaje, validar y publicar una aplicación junto con la gestión de tu negocio, todo a través del único punto de conexión /api/mcp. Consulta Build an app para ver el flujo de trabajo.

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

Presupuesto, límites y errores

What	Value
Rate limit	120 requests/minute
Tool-call cost	metered as AI credits
Budget	per API key (Option B) or per workspace; you set the cap
Token expiry	90 days (Option B Sanctum token); OAuth tokens refresh automatically

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

Code	Meaning
`-32001`	Unauthorized or session expired (Option A connectors get the OAuth challenge here)
`-32002`	Insufficient AI credits
`-32003`	Tool not permitted for this account
`-32004`	Budget cap reached

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 son visibles para ellas.

Traer tu propio agente es la vía estratégica. El MCP Server permite que tu propio cliente de IA razone directamente sobre las herramientas de SOIS, de modo que SOIS no gasta IA en tu nombre. El Chat Agent Gateway es la rampa de acceso 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 mejor se adapte a quien llama, o ambos.

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