Model Context Protocol (MCP)

3 min de lectura

Model Context Protocol (MCP)

PgArachne soporta de forma nativa el Model Context Protocol (MCP), un estándar abierto que permite a los modelos de IA (como Claude o Cursor) acceder de forma segura a sus datos y funciones como «herramientas».

¿Cómo funciona?

PgArachne actúa directamente como servidor MCP. En lugar de escribir un servidor HTTP personalizado para cada proyecto, basta con ejecutar PgArachne sobre la base de datos. PgArachne analiza automáticamente las funciones SQL permitidas y las expone a los clientes de IA mediante HTTP(S).

Funciones SQL como herramientas

Cualquier función SQL accesible a través del endpoint JSON-RPC 2.0 de PgArachne se convierte automáticamente en una «herramienta» disponible para la IA. El comportamiento por defecto (llamando a pgarachne.allowed_schemas()) expone las funciones almacenadas en el esquema api a las que el rol autenticado tiene acceso (mediante GRANT EXECUTE). El modelo de lenguaje ve el nombre de la función, sus parámetros y la descripción proveniente de los comentarios SQL.

Guía de conexión

1 a. Autenticación — Token de API (recomendado para producción)

Para una conexión permanente con la IA, utilice un token de API de larga duración. El token debe ser generado por un administrador (un miembro del rol pgarachne_admin):

-- Cambiar al rol de administrador
SET ROLE pgarachne_admin;

-- Generar un nuevo token para el rol objetivo (ej. 'app_user')
SELECT pgarachne.add_api_token('Claude Desktop', 'app_user');

Guarde la cadena devuelta. Úsela como Authorization: Bearer SU_TOKEN_DE_API en la configuración del cliente de IA.

1 b. Autenticación — Credenciales directas (desarrollo y configuraciones sencillas)

Como alternativa, es posible enviar el nombre de usuario y la contraseña de PostgreSQL directamente mediante autenticación HTTP Basic. No se requiere gestión de tokens de API ni GRANT … TO pgarachne — PgArachne se conecta directamente como el usuario indicado.

Authorization: Basic <base64(usuario:contraseña)>

Este enfoque es adecuado para pruebas locales o herramientas internas donde las credenciales ya se gestionan de forma segura en el entorno. Para integraciones de IA en producción con clientes en la nube, se recomienda el uso de tokens de API.

2. Claude Desktop

Añada PgArachne a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pgarachne": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http",
        "--url",
        "https://su-api.com/db/my_database/mcp"
      ],
      "env": {
        "Authorization": "Bearer SU_TOKEN_DE_API"
      }
    }
  }
}

Nota: Se requiere HTTP(S) para la conexión. El ejemplo usa el puente npx server-http de Anthropic, que actúa como intermediario entre el MCP estándar (stdio) y PgArachne (HTTP).

3. Cursor

En la configuración de Cursor (Settings > MCP), añada un nuevo servidor que se comunique directamente mediante HTTP (o usando el puente mencionado si su versión de Cursor no soporta servidores MCP HTTP nativos):

Type: command (con el puente npx) o http
Name: PgArachne
URL: https://su-api.com/db/my_database/mcp
Auth Header: Authorization: Bearer SU_TOKEN_DE_API

Accesibilidad pública (Ngrok)

Si está probando PgArachne de forma local y desea conectarlo a un cliente de IA en la nube (fuera de instalaciones locales), el servidor debe ser accesible públicamente mediante una URL HTTP(S).

# Ejecutar ngrok para el puerto HTTP de PgArachne (ej. 8080)
ngrok http 8080

A continuación, utilice la dirección HTTPS generada por Ngrok en la configuración de la IA.

Seguridad

El endpoint MCP respeta completamente el sistema de permisos de PostgreSQL:

Autenticación: cada petición requiere un token de API válido, un JWT o credenciales Basic válidas; las peticiones no autenticadas se rechazan de inmediato.
Autorización: la IA solo puede ver y llamar a las funciones de los esquemas permitidos para las que el rol autenticado disponga de GRANT EXECUTE.
RLS: la seguridad a nivel de fila (Row-Level Security) está completamente activa — la IA solo ve las filas a las que el rol específico tiene acceso.

Consulte Seguridad y Autenticación para una comparativa completa de todos los métodos de autenticación soportados.

← Ejemplo Hello World Herramientas →

Model Context Protocol (MCP)