ESTÁNDAR DE HERRAMIENTAS Y SERVIDORES MCP (MODEL CONTEXT PROTOCOL)

Objetivo: Definir cómo construir, integrar y extender servidores MCP (Model Context Protocol) para conectar asistentes de IA (como Claude Code o Claude Desktop) de forma segura con nuestras bases de datos, APIs de pago y servicios cloud.

LAS 4 REGLAS INQUEBRANTABLES DE MCP

[REQUIRED] MCP-001: Todo MCP Server DEBE validar sus inputs con Zod. NUNCA ejecutar consultas o comandos con argumentos sin validar.

Por qué: un servidor MCP ejecuta acciones con argumentos que propone un modelo, no una persona. Un modelo puede alucinar un argumento o repetir uno inyectado en el contenido que acaba de leer, así que la entrada es tan poco confiable como la de un endpoint público y se valida igual (S-001).

[REQUIRED] MCP-002: NUNCA exponer credenciales ni secretos en el código del servidor MCP. Los tokens y claves API se leen de variables de entorno del proceso.

Por qué: el código de un servidor MCP se comparte, se versiona y se pega en conversaciones con un modelo. Un secreto ahí escapa por más vías de las habituales, incluida la de acabar dentro del contexto de un LLM.

[REQUIRED] MCP-003: Principio de Privilegio Mínimo. Un servidor MCP que consulta la base de datos debe usar un rol con permisos acotados o funciones RPC específicas — NUNCA acceso ilimitado de superusuario.

Por qué: un servidor MCP amplifica cualquier permiso que le des, porque quien decide qué invocar es un modelo. Con service_role sobre la base de datos, una petición mal interpretada es un borrado masivo; con un rol acotado o funciones RPC concretas, es un error recuperable.

[REQUIRED] MCP-004: Todo MCP Server DEBE incluir Rate Limiting y límites de respuesta. Evita que la IA realice cientos de peticiones involuntarias o devuelva payloads de gigabytes que saturen el contexto.

Por qué: un modelo en bucle puede lanzar cientos de llamadas en segundos sin intención de hacer daño, y una respuesta enorme agota la ventana de contexto además de la cuota. El límite protege del uso accidental, que aquí es mucho más probable que el malicioso.

1. ¿QUÉ ES MCP (MODEL CONTEXT PROTOCOL)?

El Model Context Protocol (MCP) es un estándar abierto que permite a los modelos de lenguaje (LLMs) interactuar de forma segura con herramientas externas, recursos de datos y APIs locales o remotas a través de una interfaz cliente-servidor JSON-RPC 2.0.

┌────────────────────────────────┐         JSON-RPC         ┌────────────────────────────────┐
│   Cliente MCP (Claude Code /   │ ───────────────────────► │   Servidor MCP (TypeScript)    │
│   Claude Desktop / Antigravity)│ ◄─────────────────────── │  (Supabase / Stripe / R2 API)  │
└────────────────────────────────┘      Stdio / SSE         └────────────────────────────────┘

2. ESTRUCTURA Y CÓDIGO DE UN MCP SERVER COMPLETO

A continuación se muestra la implementación de referencia de un servidor MCP en TypeScript usando el SDK oficial @modelcontextprotocol/sdk.

typescript

// mcp-servers/supabase-server/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import {
  CallToolRequestSchema,
  ListToolsRequestSchema
} from '@modelcontextprotocol/sdk/types.js'
import { createClient } from '@supabase/supabase-supabase-js'
import { z } from 'zod'

// 1. Validar entorno
const SUPABASE_URL = process.env.SUPABASE_URL
const SUPABASE_SERVICE_ROLE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY

if (!SUPABASE_URL || !SUPABASE_SERVICE_ROLE_KEY) {
  console.error('Error: Faltan las variables SUPABASE_URL o SUPABASE_SERVICE_ROLE_KEY')
  process.exit(1)
}

const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)

// 2. Inicializar el Servidor MCP
const server = new Server(
  {
    name: 'supabase-mcp-server',
    version: '1.0.0'
  },
  {
    capabilities: {
      tools: {}
    }
  }
)

// 3. Schemas de Zod para validación estricta de inputs (MCP-001)
const QueryTableSchema = z.object({
  table: z.string().regex(/^[a-zA-Z0-9_]+$/, 'Nombre de tabla inválido'),
  columns: z.string().default('id, created_at'),
  limit: z.number().min(1).max(100).default(20)
})

const ExecuteRpcSchema = z.object({
  function_name: z.string().regex(/^[a-zA-Z0-9_]+$/),
  args: z.record(z.unknown()).optional()
})

// 4. Registrar la lista de herramientas disponibles
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'query_table',
      description: 'Consulta filas de una tabla permitida en Supabase con columnas explícitas.',
      inputSchema: {
        type: 'object',
        properties: {
          table: { type: 'string', description: 'Nombre de la tabla (ej. documents, teams)' },
          columns: { type: 'string', description: 'Columnas a seleccionar separadas por comas (NUNCA *)' },
          limit: { type: 'number', description: 'Cantidad máxima de registros (1-100)' }
        },
        required: ['table']
      }
    },
    {
      name: 'execute_rpc',
      description: 'Ejecuta una función almacenada segura (RPC) en la base de datos.',
      inputSchema: {
        type: 'object',
        properties: {
          function_name: { type: 'string', description: 'Nombre de la función RPC' },
          args: { type: 'object', description: 'Argumentos clave-valor para la función' }
        },
        required: ['function_name']
      }
    }
  ]
}))

// 5. Manejar la ejecución de las herramientas (tools/call)
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params

  try {
    switch (name) {
      case 'query_table': {
        const validated = QueryTableSchema.parse(args)
        
        const { data, error } = await supabase
          .from(validated.table)
          .select(validated.columns)
          .limit(validated.limit)

        if (error) throw error

        return {
          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
        }
      }

      case 'execute_rpc': {
        const validated = ExecuteRpcSchema.parse(args)

        const { data, error } = await supabase.rpc(
          validated.function_name,
          validated.args ?? {}
        )

        if (error) throw error

        return {
          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
        }
      }

      default:
        throw new Error(`Herramienta desconocida: ${name}`)
    }
  } catch (err: unknown) {
    const message = err instanceof Error ? err.message : String(err)
    return {
      isError: true,
      content: [{ type: 'text', text: `Error ejecutando ${name}: ${message}` }]
    }
  }
})

// 6. Arrancar el servidor usando transporte stdio
async function main() {
  const transport = new StdioServerTransport()
  await server.connect(transport)
  console.error('Supabase MCP Server corriendo en stdio...')
}

main().catch(console.error)

3. CONFIGURACIÓN EN CLAUDE DESKTOP Y ANTHROPIC CLI

Para registrar servidores MCP en tu entorno de desarrollo, edita el archivo de configuración global:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": ["C:/Users/usuario/projects/mcp-servers/supabase-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://xxx.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "sb-xxx-secret"
      }
    },
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server-stripe"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_xxx"
      }
    },
    "cloudflare": {
      "command": "node",
      "args": ["C:/Users/usuario/projects/mcp-servers/cloudflare-server/dist/index.js"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "cf_token_xxx",
        "CLOUDFLARE_ACCOUNT_ID": "cf_account_xxx"
      }
    }
  }
}

4. CATÁLOGO RECOMENDADO DE SERVIDORES MCP

Servidor MCP	Propósito	Prioridad	Variables requeridas
supabase-mcp	Consultas SQL asistidas, esquemas de tablas, verificación de RLS	🔴 Crítico	`SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`
stripe-mcp	Consultar clientes, eventos de pago, webhooks y productos	🔴 Crítico	`STRIPE_SECRET_KEY`
resend-mcp	Probar plantillas React Email y estado de entregabilidad	🟡 Importante	`RESEND_API_KEY`
cloudflare-mcp	Inspeccionar logs de Workers, namespaces KV y buckets R2	🟡 Importante	`CLOUDFLARE_API_TOKEN`, `ACCOUNT_ID`
github-mcp	Crear PRs, revisar issues y consultar workflows de CI/CD	🟢 Recomendado	`GITHUB_TOKEN`
playwright-mcp	Automatización E2E e inspección visual de UI en navegadores	🟢 Recomendado	N/A

5. SEGURIDAD Y AUDITORÍA DE EJECUCIÓN MCP

Petición de la IA (Llamar a herramienta query_table)
        │
        ▼
Validación de Schema Zod (MCP-001)  ──→ [Si falla: Retorna Error al LLM sin ejecutar]
        │
        ▼
Verificación de Máximo de Resultados (limit <= 100)
        │
        ▼
Ejecución en Supabase con Service Role / RPC acotado
        │
        ▼
Respuesta Sanitizada (sin revelar tokens ni hashes de contraseñas)

Respuestas Acotadas: Las herramientas que retornan listados deben truncar arrays grandes a un máximo de 100 objetos para no agotar la ventana de contexto de la IA.
Audit Logging: El servidor MCP imprime en stderr (no en stdout, ya que stdout se usa para el transporte JSON-RPC) cada invocación con su timestamp y argumentos.

ESTÁNDAR DE HERRAMIENTAS Y SERVIDORES MCP (MODEL CONTEXT PROTOCOL) ​

LAS 4 REGLAS INQUEBRANTABLES DE MCP ​

1. ¿QUÉ ES MCP (MODEL CONTEXT PROTOCOL)? ​

2. ESTRUCTURA Y CÓDIGO DE UN MCP SERVER COMPLETO ​

3. CONFIGURACIÓN EN CLAUDE DESKTOP Y ANTHROPIC CLI ​

4. CATÁLOGO RECOMENDADO DE SERVIDORES MCP ​

5. SEGURIDAD Y AUDITORÍA DE EJECUCIÓN MCP ​