MCP — Conecta cualquier cliente de IA a tu workspace

El servidor MCP de Praxsuite permite que un asistente de IA que hable Model Context Protocol lea y escriba los datos de tu workspace directamente — sin escribir código de API ni configurar endpoints.

Por debajo es el mismo DataEngine y el mismo sistema de permisos que el resto del API Gateway. Cada scope de tabla, restricción de columna y filtro a nivel de fila que tengas configurado aplica igual a las llamadas de herramientas MCP.

¿Recién llegas a Praxsuite? Necesitas una cuenta y un workspace antes de que nada de esto funcione. Empieza en Crea tu cuenta de Praxsuite y vuelve aquí.

Cómo funciona

Un solo endpoint, el mismo para todos los clientes:

https://gateway.praxsuite.com/{workspaceId}/mcp

Habla JSON-RPC 2.0 sobre Streamable HTTP (el estándar MCP actual). El cliente de IA hace POST a esta URL y recibe respuestas JSON. Te autenticas con la misma API key sk_live_ que ya usas para consultas PraxQL.

                Claude / Claude Code / Cursor / VS Code
                        |
                        |  POST (JSON-RPC 2.0)
                        |  Authorization: Bearer sk_live_xxx
                        v
          gateway.praxsuite.com/{workspaceId}/mcp
                        |
                        |  misma autenticacion + scopes
                        v
              Praxsuite DataEngine (PraxQL)
                        |
                        v
                 los datos de tu workspace

La IA nunca tiene acceso directo a la base de datos. Llama a herramientas, las herramientas pasan por tus permisos del Gateway, y sólo vuelve la información que la clave tiene permitido ver.

Como el endpoint, el transporte, la autenticación y el catálogo de herramientas son idénticos para todos los clientes, lo único que cambia de una IA a otra es dónde pegas la configuración. Para eso están las secciones por cliente de más abajo.

Qué clientes de IA se pueden conectar

El Copilot que viene con Windows no es el mismo producto que GitHub Copilot en VS Code, y no es un cliente MCP. Los caminos que Microsoft documenta para conectar un servidor MCP propio son GitHub Copilot en VS Code, Copilot Studio (para agentes que uno construye) y los conectores federados de Microsoft 365 Copilot (que aprovisiona un administrador). Ninguno de ellos es "escribir la URL de un servidor en la app de Copilot de la barra de tareas". Si Copilot de Windows es la única IA que tienes, no puedes seguir esta guía: instala VS Code y usa GitHub Copilot ahí.

Requisitos previos

Antes de conectar un cliente de IA necesitas:

1. Un workspace en Praxsuite con al menos una tabla de DataEngine.

2. Una Server API Key (sk_live_) con los scopes de tabla configurados para los datos que quieras exponer. Se crea en API Gateway → API Keys.

3. Tu Workspace ID — está en la URL del workspace o en Settings → General. Es un UUID como 3fa85f64-5717-4562-b3fc-2c963f66afa6.

Para MCP usa sólo claves sk_live_ (Server Keys). Una pk_live_ (Public Key) es para clientes de navegador y el endpoint MCP la rechaza.

Paso 1 — Crear una API key

Ve a API Gateway → API Keys en tu workspace y haz clic en Create.

Después de hacer clic en Create, copia la clave completa — empieza con sk_live_ y se muestra una sola vez.

Dos valores por defecto que conviene saber antes de salir a cazar un bug:

• Una clave nueva se crea con el grupo de herramientas Data en readwrite y todos los demás grupos (schema, apps, users, credentials, security) en None. Así que leer y escribir filas funciona de inmediato; las herramientas que crean tablas, despliegan apps o administran usuarios no aparecen en tools/list hasta que un administrador las conceda. Ver API Gateway → Credenciales → Permisos de herramientas MCP.

• AllowSchemaIntrospection viene apagado por defecto en cada scope de tabla. Es el que controla describe_table. Enciéndelo para las tablas que la IA necesite entender.

Paso 2 — Conectar tu cliente de IA

En todos los fragmentos de abajo, reemplaza {workspaceId} por el UUID de tu workspace y sk_live_your_key_here por la clave del Paso 1.

Claude Desktop

Edita claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "praxsuite": {
      "type": "http",
      "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Reinicia Claude Desktop después.

Claude Code (CLI)

La URL es un argumento posicional, no un flag:

claude mcp add --transport http praxsuite \
  https://gateway.praxsuite.com/{workspaceId}/mcp \
  --header "Authorization: Bearer sk_live_your_key_here"

Agrega --scope user para que el servidor quede disponible en todos tus proyectos y no sólo en el actual.

Cursor

Abre Settings → MCP y agrega un servidor nuevo:

{
  "praxsuite": {
    "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
    "headers": {
      "Authorization": "Bearer sk_live_your_key_here"
    }
  }
}

VS Code + GitHub Copilot

Hay dos caminos. El de la extensión es el corto.

Camino A — la extensión de Praxsuite (recomendado)

Instala Praxsuite (publisher Praxsuite, ID de extensión Praxsuite.praxsuite) desde el Marketplace de VS Code, o desde Open VSX si tu editor usa ese registro. Requiere VS Code 1.99 o superior.

Luego abre la paleta de comandos (Ctrl+Shift+P / Cmd+Shift+P) y ejecuta Praxsuite: Configure Workspace. Te pide tres cosas, en orden:

1. tu Workspace ID,

2. la URL del Gateway (https://gateway.praxsuite.com),

3. tu clave sk_live_ — que se guarda en el almacén cifrado de secretos de VS Code, nunca en un archivo de settings.

La extensión hace entonces dos cosas a la vez:

• Escribe `.vscode/mcp.json` por ti, con el servidor, la URL y el header Authorization ya completos, para que el modo agente de Copilot reciba el catálogo MCP completo. Recarga la ventana cuando te lo ofrezca.

• Registra un conjunto de herramientas de modelo de lenguaje para Copilot (praxsuite_list_tables, praxsuite_get_rows, praxsuite_execute_praxql, las de archivos y apps, y más). Éstas aparecen en Copilot Chat sin que MCP intervenga en absoluto.

También agrega una vista Praxsuite a la barra lateral, donde puedes navegar tablas y ejecutar PraxQL directamente.

La extensión no tiene login propio. Pide la misma clave sk_live_ que cualquier otro cliente — sólo te ahorra editar JSON a mano y mantiene la clave fuera de tu repositorio.

Camino B — escribir .vscode/mcp.json a mano

Crea .vscode/mcp.json en tu proyecto. Usa un input en vez de pegar la clave en el archivo, para que nunca llegue al control de versiones:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "praxsuite-key",
      "description": "Praxsuite sk_live_ API key",
      "password": true
    }
  ],
  "servers": {
    "praxsuite": {
      "type": "http",
      "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
      "headers": {
        "Authorization": "Bearer ${input:praxsuite-key}"
      }
    }
  }
}

VS Code te pide la clave la primera vez que arranca el servidor y la guarda aparte del archivo.

Para dejar el servidor disponible en todos tus proyectos en vez de uno, ejecuta MCP: Open User Configuration desde la paleta de comandos y pon el mismo bloque servers ahí. MCP: Add Server hace lo mismo con un asistente paso a paso.

Después abre Copilot Chat, cámbialo a modo Agent, y las herramientas de Praxsuite aparecen en el selector de herramientas.

Paso 3 — Verificar la conexión

Una vez conectado, pídele a la IA:

"Lista las tablas disponibles en mi workspace de Praxsuite"

Va a llamar a la herramienta list_tables y devolver los nombres y GUIDs de las tablas a las que tu clave tiene acceso. Si los ves, estás conectado.

Autenticación: por ahora, sólo API key

Todos los clientes de arriba se autentican con una clave sk_live_ en un header Authorization: Bearer. No existe un flujo de inicio de sesión en el navegador donde la IA te pida permiso y se conecte sola.

El Gateway sí publica documentos de discovery OAuth — un Protected Resource Metadata en /.well-known/oauth-protected-resource, los metadatos del authorization server, y una descripción OpenAPI — y el endpoint MCP sí acepta conectores de IA registrados, que es el camino que usa un conector personalizado de Claude.ai, configurado desde API Gateway → Credenciales → Conectores de IA. Pero no hay registration_endpoint, así que un cliente MCP cualquiera no puede registrarse y conectarse por su cuenta. Pega la clave.

Herramientas disponibles

El servidor MCP expone estas herramientas. La IA elige cuáles llamar según tus instrucciones. Lo que una clave ve en concreto lo acotan sus permisos de herramientas MCP, así que una herramienta que no puede usar está ausente de tools/list en vez de presente y fallando.

Herramientas de esquema

Herramientas de filas

Herramienta avanzada

Herramientas de archivos

Conversaciones de ejemplo

Leer datos

Tú: Muéstrame las últimas 10 órdenes de clientes en Chile

Claude: (llama list_tables -> encuentra la tabla "Orders")
        (llama describe_table -> ve las columnas Status, Country, CreatedAt)
        (llama get_rows con filtros: Country=Chile, orden: CreatedAt desc, limit: 10)
        Estas son las 10 órdenes más recientes de Chile: ...

Escribir datos

Tú: Marca la orden abc-123 como "Shipped"

Claude: (llama update_row con table_id, row_id=abc-123, values={Status:"Shipped"})
        Listo. La orden abc-123 quedó en Shipped.

Agregaciones

Tú: ¿Cuántos clientes activos tengo por país?

Claude: (llama aggregate_rows: fn=count, field=Id, group_by=Country, filtros: Status=Active)
        Clientes activos por país:
          Chile - 142
          Argentina - 87
          México - 63

Permisos y seguridad

El servidor MCP aplica exactamente las mismas reglas que una llamada normal al API Gateway:

• La clave sólo ve las tablas que están en sus Table Scopes. Las tablas sin scope son invisibles.

• Las columnas marcadas como restringidas en Column Scopes nunca se devuelven, aunque la IA las pida.

• Las reglas de enmascarado aplican — una columna enmascarada devuelve el valor enmascarado sin importar la herramienta.

• La bandera AllowSchemaIntrospection de cada scope de tabla controla si describe_table funciona para esa tabla. Viene apagada por defecto, así que un scope recién creado necesita que la enciendan antes de que la IA pueda inspeccionar la estructura de columnas.

• Las operaciones de escritura (insert_row, update_row, delete_row) exigen que la clave tenga acceso write o readwrite en esa tabla. Un scope nuevo se crea como read.

• Más allá de los scopes de tabla, los permisos de herramientas MCP deciden qué grupos de herramientas puede llamar la clave. Una clave nueva recibe Data y nada más.

Recomendación: crea una API key separada y dedicada para cada integración de IA, con los scopes mínimos necesarios. No reutilices una clave que además alimenta tu backend de producción.

Resolución de problemas

La IA dice que no encuentra mis tablas

Revisa que:

1. La clave tenga Table Scopes configurados — una clave sin scopes no ve nada.

2. AllowSchemaIntrospection esté habilitado en el scope de tabla (controla describe_table y viene apagado por defecto).

3. El Workspace ID de la URL sea el correcto.

Errores de autenticación (401)

• Verifica que la clave empiece con sk_live_ — las claves públicas (pk_live_) no son aceptadas por el endpoint MCP.

• Confirma que la clave esté Active y no vencida ni revocada en la pestaña API Keys.

• Revisa que se esté enviando el header Authorization: Bearer (algunos clientes usan x-api-key — ambos se aceptan).

• Si el mensaje dice que la clave no está habilitada para MCP, un administrador apagó ese interruptor en la clave misma. En las claves nuevas viene encendido.

Falta una herramienta que esperaba

tools/list sólo devuelve lo que la credencial puede usar de verdad. Si la herramienta que buscas pertenece a un grupo que la clave no tiene concedido, no aparece en absoluto. Concede el grupo en API Gateway → Credenciales → Permisos de herramientas MCP.

La IA puede listar tablas pero no leer ni escribir filas

La clave tiene AllowSchemaIntrospection pero puede que le falte el nivel de acceso read/write en el scope de tabla. Ve a API Keys → Edit y ajusta el nivel de acceso.

Copilot en VS Code no muestra las herramientas

• Copilot Chat tiene que estar en modo Agent; las herramientas MCP no se ofrecen en modo ask.

• Recarga la ventana después de cambiar .vscode/mcp.json.

• Mira el panel de salida del servidor MCP por si hay un error de conexión — una clave mala aparece ahí como un 401, no como una herramienta faltante.

Lo que Praxsuite nunca hace

• Nunca expone cómo se almacenan físicamente tus datos. El cliente de IA ve sólo los nombres lógicos de tablas y columnas que configuraste; la capa de almacenamiento no es direccionable desde una llamada de herramienta.

• Nunca se salta tus reglas del Gateway. No hay modo admin ni modo debug. MCP es el mismo camino de datos que cualquier otra llamada de API.

• Nunca registra tu conversación con la IA. Los Query Logs registran las llamadas de herramientas (tabla accedida, tipo de operación) igual que una llamada de API normal — no el contexto conversacional del cliente de IA.