Configurar clientes MCP

Esta guía muestra cómo conectar un cliente compatible con MCP al servidor hospedado de Soyio. Si necesitas entender permisos, entornos o modos de acceso antes de configurar un cliente, revisa la introducción a MCP.

Endpoint

Usa este endpoint en clientes compatibles con MCP remoto por Streamable HTTP:

https://mcp.soyio.id/mcp

Los clientes compatibles descubren el flujo de autorización de Soyio automáticamente y redirigen al dashboard para aprobar la conexión.

Mantén el nombre del servidor como soyio si usarás una sola conexión. Si quieres separar superficies, usa nombres como soyio-workflows o soyio-consents y declara toolsets distintos en cada URL.

Elegir toolsets desde la URL

Agrega toolsets a la URL cuando quieras limitar qué herramientas ve el cliente. Por ejemplo:

{
  "mcpServers": {
    "soyio-workflows": {
      "url": "https://mcp.soyio.id/mcp?toolsets=workflows"
    },
    "soyio-consents": {
      "url": "https://mcp.soyio.id/mcp?toolsets=core,consents"
    }
  }
}

El parámetro toolsets solo limita herramientas disponibles para esa URL. No agrega permisos nuevos ni habilita módulos que la conexión no tenga autorizados. Consulta la referencia de herramientas para ver todos los ejemplos.

Usa ?toolsets=all cuando quieras que el cliente vea todos los toolsets autorizados para esa conexión. Usa listas específicas, como ?toolsets=core,workflows, para reducir contexto en clientes de código.

Antes de conectar

1. Entra al dashboard de Soyio.
2. Abre Configuración y luego MCP si el enlace no te lleva directamente a esa sección.
3. Habilita MCP para la empresa si aún está deshabilitado.
4. Confirma qué entorno vas a autorizar: sandbox o producción.
5. Confirma qué modo de acceso corresponde. Si tienes dudas, revisa modos de acceso.

Autoriza producción solo desde clientes que ya probaste en sandbox. Si cambias de entorno o modo de acceso, revoca la conexión y crea una nueva.

Configurar clientes

La configuración exacta depende del cliente MCP. Usa el endpoint hospedado cuando el cliente soporte servidores remotos; usa mcp-remote cuando el cliente solo acepte servidores locales por comando.

Claude

En Claude Desktop, abre Settings > Connectors y agrega un conector personalizado con esta URL:

https://mcp.soyio.id/mcp

Completa el flujo de autorización cuando Claude lo solicite.

Claude Code

Agrega el servidor HTTP remoto:

claude mcp add --transport http soyio https://mcp.soyio.id/mcp

Abre una sesión de Claude Code y ejecuta /mcp para iniciar la autorización.

Codex

Agrega el servidor remoto:

codex mcp add soyio --url https://mcp.soyio.id/mcp

Si usas la configuración manual, habilita clientes MCP remotos y declara el servidor:

~/.codex/config.toml

[features]
experimental_use_rmcp_client = true

[mcp_servers.soyio]
url = "https://mcp.soyio.id/mcp"

Luego inicia sesión:

codex mcp login soyio

Cursor

En Cursor, abre la configuración de MCP y agrega un servidor remoto con esta URL:

https://mcp.soyio.id/mcp

Si Cursor te pide una configuración JSON, usa:

{
  "mcpServers": {
    "soyio": {
      "url": "https://mcp.soyio.id/mcp"
    }
  }
}

VS Code

Crea o actualiza .vscode/mcp.json en tu workspace:

.vscode/mcp.json

{
  "servers": {
    "soyio": {
      "type": "http",
      "url": "https://mcp.soyio.id/mcp"
    }
  }
}

Luego abre la paleta de comandos y ejecuta MCP: List Servers para iniciar Soyio y completar la autorización.

OpenCode

Agrega el servidor remoto a tu configuración de OpenCode:

~/.config/opencode/opencode.jsonc

{
  "mcp": {
    "soyio": {
      "type": "remote",
      "url": "https://mcp.soyio.id/mcp",
      "enabled": true
    }
  }
}

Luego inicia la autorización:

opencode mcp auth soyio

Verifica que quedó conectado:

opencode mcp list

Otros clientes

Para clientes con soporte de MCP remoto, configura:

URL: https://mcp.soyio.id/mcp
Transporte: Streamable HTTP
Autenticación: flujo interactivo del cliente

Para clientes que solo aceptan comandos locales, usa mcp-remote:

{
  "mcpServers": {
    "soyio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.soyio.id/mcp"]
    }
  }
}

En clientes que usan context_servers, como Zed, adapta la misma orden:

{
  "context_servers": {
    "soyio": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.soyio.id/mcp"],
      "env": {}
    }
  }
}

Autorizar en Soyio

Cuando el cliente inicie la autorización, Soyio abrirá una pantalla del dashboard. Revisa:

• El cliente que quiere conectarse.
• El modo de acceso: permisos del usuario o acceso completo.
• El entorno: sandbox o producción.
• La etiqueta de la conexión para reconocerla después.

Autoriza la conexión y vuelve al cliente. Los códigos pendientes expiran después de 10 minutos.

Si el cliente no vuelve automáticamente después de autorizar, regresa al cliente y ejecuta su comando de estado o login. En OpenCode, por ejemplo, usa opencode mcp list.

Uso avanzado con token bearer

Algunos clientes o integraciones permiten configurar el token manualmente. Usa este patrón solo cuando no puedas usar el flujo interactivo.

No pegues tokens MCP en chats, tickets, repositorios ni prompts. Trátalos como credenciales de acceso a Soyio.

{
  "mcpServers": {
    "soyio": {
      "url": "https://mcp.soyio.id/mcp",
      "headers": {
        "Authorization": "Bearer mcp_example_token"
      }
    }
  }
}

Preguntas frecuentes

El cliente no abre la autorización

Verifica que el servidor esté configurado como remoto HTTP y que la URL termine en /mcp. Si el cliente no soporta servidores remotos, usa mcp-remote.

El código expiró

Inicia otra conexión desde el cliente. Los códigos pendientes expiran después de 10 minutos.

El cliente muestra que Soyio está deshabilitado

Revisa que el servidor esté habilitado en la configuración local del cliente y que MCP esté habilitado para la empresa en el dashboard de Soyio.

Quiero cambiar permisos o entorno

Revoca la conexión actual y crea una conexión nueva con el modo de acceso y entorno correctos.

Quiero dejar de usar un cliente

Revoca la conexión desde Configuración > MCP. El token deja de funcionar inmediatamente.