Postgres MCP: conecta tu agente de IA a una base de datos

Un servidor Postgres MCP permite que un agente de IA inspeccione un esquema de PostgreSQL y ejecute consultas a través del Model Context Protocol. Le das al servidor una conexión a la base de datos; tu agente llama a sus herramientas para leer tablas y responder preguntas sobre los datos.

Esta guía conecta Cursor a una base de datos de muestra usando Postgres MCP Pro, un rol de base de datos separado y un modo de acceso restringido. El resultado final es fácil de comprobar: el agente debería encontrar dos proyectos activos con un presupuesto mensual combinado de $68. Debería fallar si intenta cambiar esas filas.

Puedes crear la base de datos con Managed Postgres en Lizard. El proceso MCP se ejecuta en tu computadora. Los mismos comandos SQL funcionan con una instancia local de PostgreSQL bajo tu control.

Cómo se conecta Postgres MCP a tu base de datos

El agente envía una llamada de herramienta al servidor MCP. El servidor se conecta a PostgreSQL, ejecuta la consulta y devuelve el resultado. PostgreSQL verifica los permisos del rol de base de datos de la conexión.

Usamos Postgres MCP Pro, un proyecto independiente de código abierto. Expone herramientas para listar esquemas, leer detalles de tablas y ejecutar SQL. Lizard proporciona la base de datos en esta configuración.

La conexión local entre Cursor y el proceso MCP usa stdio. Tu computadora debe poder alcanzar el endpoint de la base de datos. Los resultados de las consultas pueden entrar en el contexto de tu proveedor de IA, por lo que este tutorial usa nombres de proyectos y presupuestos inventados.

Qué necesitas

• Una nueva instancia de PostgreSQL o una base de datos desechable separada, con una cuenta de propietario que pueda crear una base de datos y un rol.
• psql en tu computadora.
• uv, que ejecuta el paquete de Python fijado.
• Cursor con servidores MCP personalizados habilitados.

Probamos el SQL y las llamadas MCP con PostgreSQL 14.20, Python 3.12.10, postgres-mcp==0.3.0 y mcp==1.30.0. La tabla de resultados a continuación registra el alcance de esas comprobaciones.

1. Crea una base de datos Postgres de muestra

En un nuevo proyecto de Lizard, agrega Managed Postgres desde el panel de control. Si ya usas Lizard CLI y has vinculado el nuevo proyecto, ejecuta:

lizard add postgres

El panel de control proporciona el host, el puerto, la base de datos y las credenciales. Sigue la guía de conexión de Managed Postgres para conectarte con psql. Usa la cuenta de propietario para esta configuración; el agente recibirá una cuenta diferente.

En psql, crea y cambia a una base de datos nueva:

CREATE DATABASE mcp_demo;
\connect mcp_demo

\connect es un comando de psql. Si usas un editor SQL, selecciona mcp_demo antes de ejecutar el siguiente bloque. Si el nombre de la base de datos ya existe, elige otro nombre y actualiza los ejemplos posteriores.

Crea una tabla con tres filas:

CREATE SCHEMA demo;

CREATE TABLE demo.projects (
  id integer PRIMARY KEY,
  name text NOT NULL,
  status text NOT NULL CHECK (status IN ('active', 'paused')),
  monthly_budget_usd numeric(10, 2) NOT NULL
);

INSERT INTO demo.projects VALUES
  (1, 'Atlas', 'active', 49.00),
  (2, 'Beacon', 'active', 19.00),
  (3, 'Cedar', 'paused', 0.00);

Estas cantidades pertenecen a los datos de muestra. No son precios de Lizard.

2. Dale al agente un rol que pueda leer la tabla de muestra

Crea un inicio de sesión sin privilegios administrativos:

CREATE ROLE mcp_reader LOGIN
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;

Luego ejecuta este comando psql para establecer su contraseña sin poner la contraseña en el historial de SQL:

\password mcp_reader

Los siguientes permisos son para la base de datos nueva mcp_demo. Las revocaciones de PUBLIC afectan a otros roles que usan esa base de datos, así que no pegues este bloque en una base de datos de aplicación compartida existente.

REVOKE ALL ON DATABASE mcp_demo FROM PUBLIC;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;

GRANT CONNECT ON DATABASE mcp_demo TO mcp_reader;
GRANT USAGE ON SCHEMA demo TO mcp_reader;
GRANT SELECT ON demo.projects TO mcp_reader;

ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET default_transaction_read_only = on;
ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET statement_timeout = '5s';

Esto otorga acceso a una tabla. Una tabla que crees más tarde necesita su propio permiso. PostgreSQL aún puede exponer nombres de objetos a través de catálogos del sistema; los permisos de tabla controlan el acceso a las filas. Consulta la referencia de GRANT de PostgreSQL.

El valor predeterminado de solo lectura ayuda a evitar errores, pero un cliente puede cambiar esa configuración. Los permisos de tabla son los que evitan que este rol escriba en demo.projects. Comprobamos que una actualización sigue fallando después de desactivar el valor predeterminado.

3. Guarda la conexión del lector fuera de tu código fuente

Construye una URL de conexión usando el nuevo rol y la base de datos mcp_demo. Mantén el host, el puerto y la configuración TLS requerida de las instrucciones de conexión de tu proveedor. Aplica codificación porcentual a los caracteres especiales de la contraseña al incluirla en una URL; PostgreSQL documenta el formato de URI de conexión.

Para un endpoint alojado que requiere TLS, la forma es:

postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

sslmode=require requiere encriptación. Si tu proveedor suministra un certificado CA y un nombre de host para comprobaciones completas de certificados, usa su configuración verify-full. Si aparece un error de certificado, comprueba que el host coincida y que el certificado sea de confianza; no lo resuelvas desactivando TLS en una conexión alojada.

Agrega .env.mcp al .gitignore de tu proyecto, luego crea ese archivo en la raíz del proyecto:

DATABASE_URI=postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

Reemplaza cada marcador de posición con los valores de conexión de tu lector. El nombre es DATABASE_URI: eso es lo que espera Postgres MCP Pro. La variable de conexión de la aplicación de Lizard se llama DATABASE_URL; pasar solo ese nombre no configurará este servidor MCP.

Mantén la conexión del propietario fuera de este archivo. En macOS o Linux, restringe el acceso al archivo del lector:

chmod 600 .env.mcp

4. Configura Postgres MCP en Cursor

Crea .cursor/mcp.json en el mismo proyecto. Si el archivo ya contiene otros servidores, agrega postgres-demo dentro de su objeto mcpServers existente.

{
  "mcpServers": {
    "postgres-demo": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--with", "mcp==1.30.0",
        "--from", "postgres-mcp==0.3.0",
        "postgres-mcp", "--access-mode=restricted"
      ],
      "envFile": "${workspaceFolder}/.env.mcp"
    }
  }
}

Cursor soporta la configuración MCP del proyecto y envFile para servidores stdio locales. Consulta su referencia de configuración MCP. Si Cursor no puede encontrar uvx, reemplaza el comando con su ruta de instalación completa.

Fija ambas versiones. Durante nuestra comprobación, instalar postgres-mcp==0.3.0 sin una restricción del SDK de MCP seleccionó mcp==2.2.0. El servidor luego falló al importar mcp.server.fastmcp. Con mcp==1.30.0, se inició y completó las pruebas a continuación.

Para comprobar el inicio del paquete antes de abrir una conexión a la base de datos, ejecuta:

uvx --python 3.12 --with 'mcp==1.30.0' \
  --from 'postgres-mcp==0.3.0' postgres-mcp --help

Habilita o reinicia postgres-demo en la configuración MCP de Cursor. Deja habilitada la aprobación de herramientas mientras compruebas la configuración, e inspecciona los argumentos SQL antes de permitir una llamada.

5. Verifica las herramientas y la respuesta

Comienza con una pregunta sobre el esquema:

Use postgres-demo to inspect the demo schema. List its tables and the columns
of demo.projects. Show the tool results. Do not change the database.

El servidor debería exponer list_schemas, list_objects, get_object_details y execute_sql. Confirma que el agente llama a las herramientas e informa id, name, status y monthly_budget_usd de la tabla.

Luego pregunta:

Using demo.projects, how many projects are active and what is their total
monthly budget in USD? Show the SQL and the database result.

Una consulta para esa respuesta es:

SELECT
  count(*) AS active_projects,
  sum(monthly_budget_usd) AS total_budget_usd
FROM demo.projects
WHERE status = 'active';

Los valores esperados son:

Finalmente, comprueba la restricción en esta tabla de muestra. La condición WHERE false asegura que la consulta no tenga filas coincidentes:

Use execute_sql to run exactly:
UPDATE demo.projects SET name = name WHERE false;
Report the tool response. Do not retry with another tool or connection.

En nuestra prueba, el modo restringido devolvió Error: Error validating query. Una conexión directa separada usando mcp_reader devolvió permission denied for table projects incluso después de que desactivamos su valor predeterminado de solo lectura. La comprobación MCP y los permisos de la base de datos rechazaron cada uno la operación.

Qué probamos

El 24 de septiembre de 2026, ejecutamos el SQL de muestra y las llamadas MCP reales contra una nueva instancia local de PostgreSQL 14.20 con datos sintéticos. Usamos Python 3.12.10, Postgres MCP Pro 0.3.0 y MCP SDK 1.30.0.

Estas comprobaciones cubren los permisos SQL y el protocolo MCP. No ejecutamos el flujo de la interfaz de usuario de Cursor ni creamos una nueva base de datos en Lizard para esta prueba. Sigue las comprobaciones anteriores contra tu propio endpoint; un indicador de MCP conectado por sí solo no prueba que las herramientas de la base de datos funcionen.

Soluciona errores comunes de conexión de Postgres MCP

¿Necesitas extensiones de PostgreSQL?

Las consultas de esquema y datos en esta guía no necesitan ninguna extensión adicional. Postgres MCP Pro también ofrece herramientas de rendimiento que tienen requisitos diferentes.

Su análisis de consultas principales usa pg_stat_statements. El análisis de índices hipotéticos usa hypopg. La disponibilidad, la configuración del servidor y los permisos de roles son importantes; crear una extensión puede requerir una acción del propietario o un cambio en el servidor. Comprueba los requisitos de extensión del proyecto antes de usar esas herramientas.

Comienza con las comprobaciones de esquema y SELECT. Un fallo relacionado con una extensión en una herramienta de ajuste no significa, por sí solo, que la conexión MCP básica esté rota.

Preguntas frecuentes

¿Es Postgres MCP lo mismo que Lizard MCP?

No. Este ejemplo usa Postgres MCP Pro para consultar una base de datos PostgreSQL. Managed Postgres proporciona esa base de datos. El conector es un proyecto separado.

¿Puedo usar un agente de IA diferente?

Sí, si su cliente soporta servidores MCP locales sobre stdio. Usa el proceso con las mismas versiones, las credenciales del rol de lectura y el modo restringido, luego sigue el formato de configuración de ese cliente. El JSON anterior es para Cursor.

¿El modo restringido reemplaza los permisos de la base de datos?

Usa ambos. El modo restringido comprueba las consultas en el servidor MCP. Los permisos de PostgreSQL limitan lo que el rol de conexión puede hacer incluso a través de otro cliente. Mantén la cuenta de propietario para migraciones y administración.

¿Creará tablas o ejecutará migraciones por mí?

Esta configuración otorga al lector acceso a la tabla de muestra. No puede crear ni cambiar el esquema de tu aplicación. Ejecuta las migraciones revisadas con tu proceso normal de implementación de aplicaciones.

Conecta la base de datos a tu aplicación

Una vez que el agente pueda inspeccionar el esquema de muestra y devolver la respuesta esperada, tendrás una base de trabajo para preguntas sobre la base de datos durante el desarrollo. Mantén las credenciales de lector del agente separadas de las credenciales de tu aplicación a medida que agregas tablas.

Crea Managed Postgres para tu proyecto, sigue la guía de conexión de base de datos, o continúa con el ejemplo de implementación de aplicación en Cursor. Para implementar un servicio MCP compartido por varios clientes, consulta la guía de servidor MCP remoto separada.