Model Context Protocol: Guia Tecnica para Desarrolladores

Guia tecnica completa del Model Context Protocol (MCP). Aprende a instalar, configurar y crear tus propios servidores MCP con ejemplos de codigo en TypeScript y Python. Incluye integraciones con GitHub, PostgreSQL, Filesystem y mas.

Robert Cojocaru

23 days ago

Que es el Model Context Protocol (MCP)?

El Model Context Protocol (MCP) es un estandar abierto creado por Anthropic que permite a los LLMs conectarse con herramientas externas de forma estandarizada. Funciona como un protocolo cliente-servidor donde los modelos de IA pueden ejecutar acciones en sistemas externos.

Arquitectura de MCP

MCP sigue una arquitectura cliente-servidor:

Componente	Descripcion	Ejemplo
Host	Aplicacion que inicia conexiones	Claude Desktop, IDEs
Cliente	Mantiene conexion 1:1 con servidor	Integrado en el host
Servidor	Expone recursos y herramientas	GitHub MCP, Filesystem MCP

Los tres primitivos

Tools: Funciones que el modelo puede ejecutar
Resources: Datos que el modelo puede leer
Prompts: Templates reutilizables de contexto

Instalacion del SDK

TypeScript/Node.js

npm install @modelcontextprotocol/sdk

Python

pip install mcp

Crear tu primer servidor MCP

Servidor basico en TypeScript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "mi-servidor", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Definir una herramienta
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "saludar",
    description: "Saluda a una persona",
    inputSchema: {
      type: "object",
      properties: {
        nombre: { type: "string", description: "Nombre de la persona" }
      },
      required: ["nombre"]
    }
  }]
}));

// Implementar la herramienta
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "saludar") {
    const nombre = request.params.arguments.nombre;
    return { content: [{ type: "text", text: `Hola, ${nombre}!` }] };
  }
});

// Iniciar servidor
const transport = new StdioServerTransport();
await server.connect(transport);

Servidor basico en Python

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("mi-servidor")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="saludar",
            description="Saluda a una persona",
            inputSchema={
                "type": "object",
                "properties": {
                    "nombre": {"type": "string", "description": "Nombre"}
                },
                "required": ["nombre"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "saludar":
        return [TextContent(type="text", text=f"Hola, {arguments['nombre']}!")]

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Configurar Claude Desktop

Edita el archivo de configuracion de Claude Desktop:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mi-servidor": {
      "command": "node",
      "args": ["/ruta/a/mi-servidor/build/index.js"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/usuario/proyectos"
      ]
    }
  }
}

Servidores MCP populares con ejemplos

1. Filesystem Server

Permite a Claude leer y escribir archivos en tu sistema.

Instalacion:

npx -y @modelcontextprotocol/server-filesystem /ruta/permitida

Configuracion:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/usuario/Documents",
        "/Users/usuario/proyectos"
      ]
    }
  }
}

Uso en Claude: "Lee el archivo package.json de mi proyecto"

2. GitHub Server

Gestiona repositorios, issues y pull requests.

Instalacion:

npm install -g @modelcontextprotocol/server-github

Configuracion:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tu_token_aqui"
      }
    }
  }
}

Herramientas disponibles:

Tool	Descripcion
create_repository	Crear nuevo repositorio
search_repositories	Buscar repositorios
create_issue	Crear issue
create_pull_request	Crear PR
push_files	Subir archivos
list_commits	Listar commits

Uso en Claude: "Crea un issue en mi repo describiendo este bug"

3. PostgreSQL Server

Ejecuta consultas SQL en tu base de datos.

Instalacion:

npm install -g @modelcontextprotocol/server-postgres

Configuracion:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://usuario:password@localhost:5432/mi_base_de_datos"
      ]
    }
  }
}

Uso en Claude: "Muestrame los ultimos 10 usuarios registrados"

4. Playwright Server

Automatizacion de navegador web.

Instalacion:

npm install -g @playwright/mcp

Configuracion:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Herramientas disponibles:

Tool	Descripcion
browser_navigate	Navegar a URL
browser_click	Click en elemento
browser_type	Escribir texto
browser_snapshot	Capturar estado de pagina
browser_screenshot	Tomar screenshot

Uso en Claude: "Ve a github.com y busca repositorios de MCP"

5. Supabase Server

Interactua con tu backend de Supabase.

Instalacion:

npx supabase mcp

Configuracion:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "supabase", "mcp"],
      "env": {
        "SUPABASE_URL": "https://tu-proyecto.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "tu_service_role_key"
      }
    }
  }
}

Crear un servidor MCP avanzado

Ejemplo de servidor que expone recursos y herramientas:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ListToolsRequestSchema,
  ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "api-server", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

// Base de datos simulada
const usuarios = [
  { id: 1, nombre: "Ana", email: "ana@ejemplo.com" },
  { id: 2, nombre: "Carlos", email: "carlos@ejemplo.com" },
];

// Listar recursos disponibles
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [{
    uri: "api://usuarios",
    name: "Lista de usuarios",
    mimeType: "application/json"
  }]
}));

// Leer un recurso
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  if (request.params.uri === "api://usuarios") {
    return {
      contents: [{
        uri: "api://usuarios",
        mimeType: "application/json",
        text: JSON.stringify(usuarios, null, 2)
      }]
    };
  }
});

// Listar herramientas
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "crear_usuario",
      description: "Crea un nuevo usuario",
      inputSchema: {
        type: "object",
        properties: {
          nombre: { type: "string" },
          email: { type: "string", format: "email" }
        },
        required: ["nombre", "email"]
      }
    },
    {
      name: "buscar_usuario",
      description: "Busca usuario por nombre",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string" }
        },
        required: ["query"]
      }
    }
  ]
}));

// Ejecutar herramientas
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case "crear_usuario":
      const nuevoId = usuarios.length + 1;
      const nuevoUsuario = { id: nuevoId, ...args };
      usuarios.push(nuevoUsuario);
      return {
        content: [{
          type: "text",
          text: `Usuario creado con ID: ${nuevoId}`
        }]
      };

    case "buscar_usuario":
      const resultados = usuarios.filter(u =>
        u.nombre.toLowerCase().includes(args.query.toLowerCase())
      );
      return {
        content: [{
          type: "text",
          text: JSON.stringify(resultados, null, 2)
        }]
      };

    default:
      throw new Error(`Herramienta desconocida: ${name}`);
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Debugging de servidores MCP

Usar el Inspector MCP

npx @modelcontextprotocol/inspector node build/index.js

Esto abre una interfaz web donde puedes:

Ver herramientas y recursos disponibles
Probar llamadas a herramientas
Inspeccionar respuestas

Logs en Claude Desktop

macOS:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows (PowerShell):

Get-Content -Path "$env:APPDATA\Claude\Logs\mcp*.log" -Wait

Mejores practicas

Validacion de entrada: Usa JSON Schema para validar argumentos
Manejo de errores: Retorna mensajes de error claros
Permisos minimos: Solo expone lo necesario
Documentacion: Descripciones claras en tools y resources
Testing: Usa el Inspector antes de desplegar

Recursos adicionales

Especificacion oficial: https://spec.modelcontextprotocol.io
SDK TypeScript: https://github.com/modelcontextprotocol/typescript-sdk
SDK Python: https://github.com/modelcontextprotocol/python-sdk
Servidores oficiales: https://github.com/modelcontextprotocol/servers
Inspector MCP: https://github.com/modelcontextprotocol/inspector

MCP esta transformando como los desarrolladores construyen aplicaciones de IA. Con estos ejemplos ya puedes empezar a crear tus propias integraciones.