Tutorial práctico de MCP: guía completa para que Cursor consulte bases de datos y llame APIs

El miércoles pasado por la tarde, estaba desarrollando una función de análisis de datos y necesitaba saber cuántos usuarios nuevos se habían registrado en diciembre. Como siempre, tuve que abrir DataGrip, escribir una consulta SQL, ejecutarla, copiar el resultado y pegarlo de vuelta en el código. Solo por esa consulta sencilla, cambié de ventana tres veces y perdí dos minutos.

Entonces pensé: uso Cursor todos los días para programar; la IA ya me ayuda a escribir funciones y corregir bugs, ¿por qué no puede consultar la base de datos directamente?

Después de configurar MCP, ahora le pregunto directamente en Cursor: «¿Cuántos usuarios nuevos hubo en diciembre?» y la IA responde al instante. Sin cambiar de ventana, sin escribir SQL: la eficiencia se duplica.

Cuando oí hablar de MCP por primera vez, también me costó entenderlo. Server, Client, Protocol… suena complicado, pero los tutoriales online o son demasiado teóricos (media hora de diagramas de arquitectura) o demasiado básicos (un Hello World y listo). Me tomó dos días de prueba y error para entender cómo configurarlo.

Por eso, en este artículo quiero enseñarte paso a paso, de la forma más directa posible, cómo configurar MCP para que la IA consulte bases de datos y llame APIs. En 15 minutos lo tienes listo y puedes usarlo de inmediato.

Qué es MCP y por qué lo necesitas

MCP explicado en lenguaje sencillo

MCP significa Model Context Protocol (protocolo de contexto del modelo). Suena académico, ¿verdad? En realidad, es como darle a la IA un «cinturón de herramientas».

Antes, la IA era como un consultor muy inteligente: le hacías preguntas, te daba consejos y escribía código, pero no podía hacer nada por sí misma. Tenías que copiar sus sugerencias y ejecutarlas tú.

Con MCP, la IA se convierte en un verdadero asistente: no solo aconseja, sino que trabaja directamente. Consultar bases de datos, llamar APIs, leer archivos… lo hace sola.

Método tradicional vs. método MCP

Un ejemplo concreto: quieres saber qué producto tuvo las ventas más altas el mes pasado.

Método tradicional (sin MCP):

1. Tú: pides a la IA que escriba una consulta SQL
2. IA: te devuelve el código SQL
3. Tú: copias el SQL y cambias al cliente de base de datos
4. Tú: pegas el SQL y lo ejecutas
5. Tú: copias el resultado de la consulta
6. Tú: vuelves a Cursor y se lo pegas a la IA
7. IA: continúa el análisis con ese resultado

Todo el flujo implica ir y venir entre tres ventanas. Molesto.

Método MCP:

1. Tú: le preguntas directamente «¿Qué producto tuvo las ventas más altas el mes pasado?»
2. IA: consulta la base de datos automáticamente y te da la respuesta

Un solo paso. Al menos 5 veces más eficiente.

Conceptos clave (3 minutos para entenderlos)

La arquitectura de MCP es muy simple: tres roles.

MCP Client (el cerebro de la IA que usa herramientas)
Es la herramienta de IA que usas, como Cursor o Claude Desktop. Entiende tu necesidad y decide si usar herramientas.

MCP Server (el camarero que ofrece herramientas)
Es el servicio que configuras para darle a la IA una capacidad concreta. Por ejemplo, un MCP Server de base de datos permite consultar datos; uno de API permite llamar endpoints.

Tools (capacidades concretas)
Las funciones que expone cada MCP Server. Un Server de base de datos puede tener herramientas como «consultar estructura de tablas», «ejecutar SELECT» o «contar filas».

Analogía: la IA es un trabajador (Client), el MCP Server es la caja de herramientas con llave inglesa y martillo (Tools). Si pides clavar un clavo, la IA sabe sacar el martillo.

Con estos tres conceptos, entenderás qué hace cada parte de la configuración.

Caso práctico 1: integración con SQLite

Por qué empezar con SQLite

La gran ventaja de SQLite es la simplicidad: no instalas un servicio de base de datos ni configuras puertos; un archivo es la base de datos entera. Ideal para practicar.

Cuando domines el flujo, cambiar a PostgreSQL o MySQL es el mismo procedimiento.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Preparación: crear una base de datos de prueba

Primero crea algunos datos para probar las consultas. Crea un archivo test.db:

-- Crear tabla de usuarios
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

-- Crear tabla de pedidos
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER,
    product_name TEXT,
    amount REAL,
    order_date TEXT DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- Insertar usuarios de prueba
INSERT INTO users (name, email) VALUES
    ('张三', '[email protected]'),
    ('李四', '[email protected]'),
    ('王五', '[email protected]');

-- Insertar pedidos de prueba
INSERT INTO orders (user_id, product_name, amount) VALUES
    (1, 'MacBook Pro', 12999.00),
    (1, 'AirPods', 1299.00),
    (2, 'iPhone 15', 5999.00),
    (3, 'iPad Air', 4799.00),
    (3, 'Apple Watch', 2999.00);

Puedes ejecutar este SQL con cualquier herramienta SQLite (DB Browser, línea de comandos, etc.) o directamente con Python:

import sqlite3

conn = sqlite3.connect('test.db')
cursor = conn.cursor()

# Ejecutar las sentencias SQL anteriores
# ...

conn.commit()
conn.close()

Configurar el MCP Server (la parte clave)

Esta es la sección más importante del tutorial. El archivo de configuración de MCP puede estar en dos ubicaciones, según tu necesidad:

Configuración global (válida para todos los proyectos):

• Windows: C:\Users\tu_usuario\.cursor\mcp.json
• Mac/Linux: ~/.cursor/mcp.json

Configuración a nivel de proyecto (solo el proyecto actual):

• .cursor/mcp.json en la raíz del proyecto

Recomiendo empezar con la configuración de proyecto; cuando funcione, puedes moverla a la global.

Crea el archivo .cursor/mcp.json con este contenido:

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "D:/path/to/your/test.db"
      ]
    }
  }
}

Puntos clave (donde muchos se atascan):

1. mcpServers: nombre de campo fijo, no lo cambies
2. "sqlite": nombre que le das a este Server; la IA lo verá
3. command: "npx": ejecuta el MCP Server con npx, sin instalación manual
4. args: argumentos del comando
   • -y: confirma la instalación automáticamente
   • @modelcontextprotocol/server-sqlite: paquete oficial del MCP Server para SQLite
   • --db-path: ruta al archivo de base de datos (¡debe ser ruta absoluta!)

Usuarios de Windows: usa barra normal / o doble barra invertida \\, nunca barra invertida simple:

• ✅ D:/projects/test.db
• ✅ D:\\projects\\test.db
• ❌ D:\projects\test.db (provocará error)

Reiniciar Cursor y verificar la configuración

Después de guardar el archivo, debes reiniciar Cursor por completo: no basta con cerrar la ventana, hay que salir de la aplicación.

Tras reiniciar, puedes comprobar en la configuración de Cursor si MCP está activo:

1. Abre ajustes (Ctrl+,)
2. Busca «MCP»
3. Deberías ver el SQLite Server configurado

O más directo: haz una pregunta relacionada con la base de datos y mira si la IA invoca MCP.

Demostración práctica

Con la configuración lista, puedes usarlo así:

Consulta 1: ver qué tablas hay

Tú: ¿Qué tablas hay en la base de datos?
IA: [invoca MCP] Hay dos tablas: users y orders

Consulta 2: contar usuarios

Tú: ¿Cuántos usuarios hay en total?
IA: [ejecuta SELECT COUNT(*) FROM users] Hay 3 usuarios en total

Consulta 3: pedidos de un usuario

Tú: ¿Qué compró Zhang San?
IA: [ejecuta consulta con JOIN] Zhang San compró:
- MacBook Pro (12999 yuanes)
- AirPods (1299 yuanes)
Total: 14298 yuanes

Consulta 4: análisis agregado

Tú: ¿Qué usuario gastó más?
IA: [ejecuta GROUP BY] Zhang San gastó más, total 14298 yuanes

¿Lo ves? No escribes SQL; la IA lo resuelve sola. Ese es el poder de MCP.

Solución de problemas frecuentes

Problema 1: el MCP Server no arranca
Síntoma: la IA responde pero no consulta la base de datos
Solución:

• Revisa la sintaxis del archivo (JSON válido, sin comas de más)
• Confirma que reiniciaste Cursor por completo
• Mira los logs de salida de Cursor y busca errores relacionados con «MCP»

Problema 2: no encuentra el archivo de base de datos
Síntoma: error «cannot open database file»
Solución:

• Confirma que la ruta es absoluta, no relativa
• En Windows, revisa la dirección de las barras
• Confirma que el archivo existe (ls o dir)

Problema 3: error de permisos
Síntoma: Permission denied
Solución:

• Revisa permisos de lectura/escritura del archivo de base de datos
• En Windows: clic derecho → Propiedades → Seguridad, y confirma lectura para tu usuario

Truco de depuración: en VS Code (Cursor), abre el panel «Output» (View → Output), elige el canal «MCP» y verás el log detallado de errores.

Caso práctico 2: integración con PostgreSQL

Escenario avanzado: base de datos de producción

SQLite sirve para aprender y proyectos pequeños, pero en el trabajo real suele usarse PostgreSQL, MySQL u otro motor de producción. La buena noticia: el procedimiento es el mismo, solo cambian los parámetros.

Aquí uso PostgreSQL como ejemplo; MySQL es similar.

Diferencias de configuración: conexión y variables de entorno

PostgreSQL es cliente/servidor y requiere datos de conexión. Nunca pongas la contraseña directamente en el archivo de configuración; es el error de seguridad más común.

Lo correcto es usar variables de entorno.

Crea un archivo .env en la raíz del proyecto (recuerda añadirlo a .gitignore):

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=myapp
POSTGRES_USER=readonly_user
POSTGRES_PASSWORD=your_secure_password

Luego configura .cursor/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "--stdio"
      ],
      "env": {
        "POSTGRES_HOST": "${POSTGRES_HOST}",
        "POSTGRES_PORT": "${POSTGRES_PORT}",
        "POSTGRES_DATABASE": "${POSTGRES_DATABASE}",
        "POSTGRES_USER": "${POSTGRES_USER}",
        "POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}"
      }
    }
  }
}

Puntos clave:

• --stdio: comunicación por entrada/salida estándar (modo local)
• env: variables de entorno; Cursor lee el .env del proyecto

Buenas prácticas de seguridad (muy importante)

Dar acceso a la base de datos a la IA exige priorizar la seguridad. Errores que ya cometí para que tú no los repitas:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

1. Usar cuenta de solo lectura

¡No des permisos de escritura a la IA! Si malinterpreta tu petición y ejecuta DELETE o UPDATE, lo lamentarás.

Crear usuario de solo lectura:

-- Crear usuario de solo lectura
CREATE USER readonly_user WITH PASSWORD 'secure_password';

-- Conceder solo permiso SELECT
GRANT CONNECT ON DATABASE myapp TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;

-- Asegurar SELECT en tablas futuras
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO readonly_user;

2. Limitar el alcance del acceso

Si hay tablas sensibles (contraseñas de usuario, pagos), no dejes que la IA las toque:

-- Revocar acceso a tablas sensibles
REVOKE SELECT ON TABLE user_passwords FROM readonly_user;
REVOKE SELECT ON TABLE payment_info FROM readonly_user;

3. Réplica de lectura en producción

Si de verdad usas MCP en producción (recomiendo no hacerlo al principio), conéctate al menos a una réplica de lectura (Read Replica), no al master. Si una consulta compleja de la IA ralentiza la base, no afectará al servicio en línea.

Demostración práctica

Con la configuración lista, puedes hacer cosas que SQLite no cubre tan bien:

Consulta compleja: JOIN entre varias tablas

Tú: Calcula el salario medio por departamento
IA: [ejecuta consulta compleja]
SELECT d.name, AVG(e.salary) as avg_salary
FROM departments d
JOIN employees e ON d.id = e.department_id
GROUP BY d.name
ORDER BY avg_salary DESC;

Resultado:
- Tecnología: media 15000 yuanes
- Producto: media 12000 yuanes
- Operaciones: media 10000 yuanes

Análisis de rendimiento: plan de ejecución

Tú: ¿Por qué va tan lenta esta consulta?
IA: [ejecuta EXPLAIN] No usa índice; sugiere índice en user_id

Análisis de datos: informe

Tú: Usuarios nuevos por día en los últimos 7 días
IA: [consulta con ventana temporal]
2024-01-10: 45 personas
2024-01-11: 52 personas
...

Problemas frecuentes

Problema 1: timeout de conexión
Síntoma: timeout connecting to database
Solución:

• Comprueba que la base esté en marcha (pg_isready)
• Revisa firewall
• Confirma host y port

Problema 2: fallo de autenticación
Síntoma: authentication failed
Solución:

• Revisa usuario y contraseña
• Confirma que pg_hba.conf permite la conexión
• Prueba con psql manualmente

Problema 3: permisos insuficientes
Síntoma: permission denied for table xxx
Solución:

• Puede ser buena señal: el rol de solo lectura funciona
• Si necesitas esa tabla, un admin debe ejecutar el GRANT correspondiente

Caso práctico 3: integración con llamadas a API

Caso de uso: que la IA llame servicios externos

La base de datos resuelve consultas internas, pero a veces necesitas datos de APIs externas, por ejemplo:

• stars e issues de un repositorio en GitHub
• microservicios internos de la empresa
• clima, tipos de cambio u otros datos en tiempo real

Con MCP, la IA también puede llamar esos endpoints.

Configurar un MCP Server de tipo HTTP

Las APIs no requieren instalar un paquete MCP Server; basta con configurar el tipo HTTP.

Ejemplo con la API de GitHub en .cursor/mcp.json:

{
  "mcpServers": {
    "github-api": {
      "url": "https://api.github.com",
      "headers": {
        "Accept": "application/vnd.github.v3+json",
        "User-Agent": "Cursor-MCP-Client"
      }
    }
  }
}

Si la API requiere autenticación (repos privados en GitHub), añade el token:

{
  "mcpServers": {
    "github-api": {
      "url": "https://api.github.com",
      "headers": {
        "Accept": "application/vnd.github.v3+json",
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "User-Agent": "Cursor-MCP-Client"
      }
    }
  }
}

Guarda el token en .env:

GITHUB_TOKEN=ghp_your_personal_access_token_here

Cómo obtener un token de GitHub:

1. GitHub → Settings → Developer settings
2. Personal access tokens → Tokens (classic)
3. Generate new token → marca los permisos necesarios (repo, user, etc.)
4. Copia el token (solo se muestra una vez; guárdalo)

Demostración práctica

Con la configuración lista:

Información del repositorio

Tú: ¿Cuántas stars tiene el repo facebook/react?
IA: [GET /repos/facebook/react]
React tiene 218.345 stars y 79.234 forks

Issues recientes

Tú: ¿Qué issues recientes hay en facebook/react?
IA: [GET /repos/facebook/react/issues?state=open&per_page=5]
Últimos 5 issues:
1. [Bug] useEffect se ejecuta dos veces en modo estricto
2. [Feature] Soporte para nueva API de Suspense
3. [Question] Cómo optimizar listas grandes
...

Frecuencia de commits

Tú: ¿Cuántos commits hubo en facebook/react la semana pasada?
IA: [GET /repos/facebook/react/commits?since=...]
43 commits en 7 días; principales contribuidores...

Configurar una API personalizada

Las APIs internas se configuran igual. Supón un servicio de usuarios:

{
  "mcpServers": {
    "user-service": {
      "url": "https://api.yourcompany.com/user-service",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_KEY}",
        "Content-Type": "application/json"
      }
    }
  }
}

Entonces puedes preguntar:

Tú: Historial de pedidos del usuario ID 12345
IA: [llama API interna] El usuario 12345 hizo 8 pedidos en 30 días, total 3200 yuanes

Precauciones

Límite de tasa de la API
Muchas APIs limitan la frecuencia. GitHub gratis: 60 llamadas/hora. Si la IA llama en exceso, activarás el rate limit.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Soluciones:

• Usa token autenticado (GitHub sube a 5000/hora)
• Indica a la IA «usa la API lo menos posible; reutiliza resultados»

Riesgos de seguridad
Dar a la IA acceso a APIs es darle capacidad de actuar sobre servicios externos. Obligatorio:

• Token de solo lectura (sin escritura)
• Rotar tokens con regularidad
• Monitorizar logs de llamadas

Técnicas avanzadas y buenas prácticas

Varios MCP Servers a la vez

En un proyecto puedes configurar varios MCP Servers; la IA elige la herramienta adecuada.

Ejemplo de mi configuración:

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "D:/projects/myapp/data.db"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "--stdio"],
      "env": {
        "POSTGRES_HOST": "${POSTGRES_HOST}",
        "POSTGRES_PORT": "${POSTGRES_PORT}",
        "POSTGRES_DATABASE": "${POSTGRES_DATABASE}",
        "POSTGRES_USER": "${POSTGRES_USER}",
        "POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}"
      }
    },
    "github-api": {
      "url": "https://api.github.com",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "Accept": "application/vnd.github.v3+json"
      }
    }
  }
}

Después puedes preguntar:

Tú: ¿Cuántos usuarios hay en SQLite local y cuántas stars tiene nuestro repo en GitHub?
IA: [sqlite MCP] 245 usuarios locales
    [github-api MCP] 1,2k stars en el repo

La IA elige la herramienta según la pregunta.

Configuración de proyecto vs. global

Configuración de proyecto (.cursor/mcp.json):

• Para bases de datos y APIs específicas del proyecto
• Ventaja: proyectos aislados; la config puede ir a Git (excluye secretos)
• Inconveniente: repetir en cada proyecto

Configuración global (~/.cursor/mcp.json):

• Para herramientas genéricas (sistema de archivos, APIs comunes)
• Ventaja: una sola vez para todos los proyectos
• Inconveniente: más caos; no está en el repo del equipo

Recomendación:

• Base de datos y APIs del proyecto → configuración de proyecto
• GitHub, clima, etc. → configuración global
• Al terminar, documenta la config de proyecto para el equipo

Optimización del rendimiento

Cada llamada MCP ejecuta una consulta o petición real; muchas llamadas ralentizan el flujo.

1. Pedir a la IA que cachee resultados

Tú: Lista de usuarios (recuerda este resultado, lo usaré después)
IA: [consulta y recuerda] 245 usuarios...

Tú: De esos 245, ¿cuántos son VIP?
IA: [sin volver a consultar, analiza el resultado anterior]

2. Limitar complejidad de consultas
Evita SQL con diez niveles de anidación; si la IA lo genera, detén y optimiza manualmente.

3. Índices en la base de datos
La IA no compensa una base lenta; añade índices donde toque.

Depuración

1. Log de MCP
Panel Output (View → Output), canal «MCP»:

• arranque del Server
• parámetros y respuestas de cada herramienta
• stack de errores

2. Probar la configuración
Tras escribir la config, prueba con algo simple:

Tú: Prueba la conexión a la base de datos y dime qué tablas hay

3. Verificación manual
Si la IA dice que falló, ejecuta tú la consulta para ver si es SQL, permisos o conexión.

Significado de códigos de error frecuentes

• ENOENT: archivo o ruta inexistente (revisa la ruta)
• ECONNREFUSED: conexión rechazada (base apagada o puerto incorrecto)
• EACCES: permisos insuficientes (archivo o base de datos)
• ERR_MODULE_NOT_FOUND: paquete MCP no instalado (revisa npx)
• ETIMEDOUT: timeout (red o consulta muy lenta)

Conclusión

Después de configurar MCP, mi forma de programar cambió de verdad.

Antes, consultar datos implicaba saltar entre tres ventanas y cortar el hilo del pensamiento. Ahora pregunto en Cursor y la IA responde al instante; el foco se mantiene en la lógica del código.

Este artículo supera las 3000 palabras, pero el núcleo son tres cosas:

1. Entender el concepto: MCP da herramientas a la IA para actuar, no solo aconsejar
2. Seguir la configuración: SQLite para practicar, PostgreSQL en producción, API para ampliar capacidades
3. Cuidar la seguridad: solo lectura, variables de entorno, no tocar el master de producción

Hoy, dedica 15 minutos a configurar un MCP con SQLite. Verás que la mejora no es un 10 % o 20 %, sino otra forma de trabajar.

MCP sigue siendo relativamente nuevo; el equipo oficial itera rápido y la comunidad aporta Servers nuevos. Tengo una lista en GitHub por si quieres explorar herramientas para tu caso.

Si tienes dudas, déjalas en comentarios; responderé.