← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 12: MCP Servers

Por: Artiko
opencodeaimcpmodel-context-protocolherramientas

Capitulo 12: MCP Servers

< Volver al Indice del Tutorial

Qué es MCP

Model Context Protocol (MCP) es un protocolo estandarizado que permite extender las capacidades de un agente AI con herramientas externas. En lugar de que el agente solo pueda leer archivos y ejecutar comandos del sistema, MCP le permite conectarse a servicios como Sentry, navegadores, bases de datos, APIs de documentación y cualquier otra herramienta que implemente el protocolo.

OpenCode soporta MCP de forma nativa. Puedes configurar múltiples servidores MCP que el agente descubrirá y usará automáticamente cuando lo necesite. El protocolo define un estándar para que las herramientas se registren, describan sus capacidades y reciban invocaciones del modelo.

flowchart LR
    A[OpenCode] -->|Descubre herramientas| B[MCP Server 1]
    A -->|Descubre herramientas| C[MCP Server 2]
    A -->|Descubre herramientas| D[MCP Server 3]
    B -->|Sentry: issues, errores| E[Resultado]
    C -->|Playwright: navegador| E
    D -->|Context7: docs| E
    E -->|Respuesta enriquecida| A

La ventaja de MCP sobre ejecutar comandos directamente es que las herramientas MCP se autodocumentan: el modelo sabe exactamente qué puede hacer cada herramienta, qué parámetros acepta y qué tipo de resultado devuelve. Esto hace que el agente use las herramientas de forma más precisa y eficiente.

Configuración en opencode.json

Los MCP servers se definen en el archivo opencode.json bajo la clave "mcp":

{
  "mcp": {
    "servidor-local": {
      "type": "local",
      "command": ["npx", "-y", "mi-comando-mcp"],
      "environment": { "VAR": "valor" },
      "enabled": true
    },
    "servidor-remoto": {
      "type": "remote",
      "url": "https://mi-servidor.com",
      "headers": { "Authorization": "Bearer TOKEN" }
    }
  }
}

Existen dos tipos principales de servidores MCP: locales (que ejecutan un proceso en tu máquina) y remotos (que conectan a un servicio HTTP externo).

Servidores Locales (stdio)

Los servidores locales ejecutan un proceso en tu máquina y se comunican via stdio (standard input/output). Son los más comunes y fáciles de configurar. OpenCode inicia el proceso automáticamente cuando necesita alguna de sus herramientas.

{
  "mcp": {
    "mi-mcp-local": {
      "type": "local",
      "command": ["npx", "-y", "mi-mcp-command"],
      "environment": {
        "API_KEY": "tu-api-key",
        "DEBUG": "true"
      },
      "enabled": true
    }
  }
}

Propiedades disponibles

El servidor se inicia automáticamente cuando OpenCode arranca la sesión. El proceso se comunica con OpenCode a través de stdio: OpenCode envía peticiones como JSON por stdin y el servidor responde por stdout.

Formato del comando

El array command soporta cualquier ejecutable:

// Paquete npm
"command": ["npx", "-y", "@sentry/mcp-server"]

// Script Python
"command": ["python", "-m", "mi_mcp_server"]

// Binario directo
"command": ["/usr/local/bin/mi-mcp"]

// Con argumentos
"command": ["npx", "-y", "mi-mcp", "--port", "3000", "--verbose"]

El flag -y en npx es importante: acepta automáticamente la instalación del paquete si no está descargado, evitando que el proceso se quede esperando input del usuario.

Servidores Remotos (HTTP)

Los servidores remotos conectan a un servicio MCP que corre en otro lugar, accesible via HTTP. Son útiles cuando el servicio MCP está alojado en la nube, en otro equipo de tu red, o es proporcionado por un tercero.

{
  "mcp": {
    "mi-remote": {
      "type": "remote",
      "url": "https://mi-mcp-server.com/mcp",
      "headers": {
        "Authorization": "Bearer tu-api-key"
      }
    }
  }
}

Propiedades disponibles

Los servidores remotos usan HTTP para la comunicación, lo que los hace ideales para servicios que necesitan alta disponibilidad o que son compartidos por un equipo. La latencia es mayor que con servidores locales, pero la configuración es más simple ya que no necesitas instalar ni ejecutar nada en tu máquina.

Autenticación OAuth

OpenCode soporta OAuth para servidores MCP remotos. Esto es especialmente útil para servicios que requieren autenticación de usuario, como GitHub, Slack o herramientas internas de tu empresa.

Comando de autenticación

opencode mcp auth nombre-servidor

Este comando inicia el flujo OAuth: abre tu navegador, te redirige al proveedor de identidad, y una vez autenticado, almacena los tokens de forma segura.

Registro dinámico de clientes

OpenCode soporta el registro dinámico de clientes OAuth (Dynamic Client Registration). Esto significa que si el servidor MCP implementa el endpoint de registro, OpenCode puede registrarse automáticamente como cliente OAuth sin necesidad de credenciales preconfiguradas.

El flujo es:

sequenceDiagram
    participant O as OpenCode
    participant S as Servidor MCP
    participant P as Proveedor OAuth
    
    O->>S: Petición (sin auth)
    S-->>O: 401 + endpoints OAuth
    O->>P: Registro dinámico de cliente
    P-->>O: client_id + client_secret
    O->>P: Solicitar autorización (navegador)
    P-->>O: Token de acceso
    O->>S: Petición (con token)
    S-->>O: Respuesta exitosa

Credenciales preregistradas

Cuando ya tienes credenciales OAuth del servicio (porque te las proporcionó el administrador o las generaste manualmente), puedes configurarlas directamente:

{
  "mcp": {
    "servicio-preregistrado": {
      "type": "remote",
      "url": "https://servicio.com/mcp",
      "oauth": {
        "clientId": "tu-client-id",
        "clientSecret": "tu-client-secret"
      }
    }
  }
}

OAuth automático (por defecto)

Si el servidor responde con un 401, OpenCode detecta automáticamente los endpoints OAuth y abre el navegador para autenticación:

{
  "mcp": {
    "servicio-oauth": {
      "type": "remote",
      "url": "https://servicio.com/mcp"
    }
  }
}

No necesitas configurar nada adicional. OpenCode maneja todo el flujo.

Deshabilitar OAuth

Para deshabilitar OAuth y usar solo headers estáticos:

{
  "mcp": {
    "servicio-sin-oauth": {
      "type": "remote",
      "url": "https://servicio.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer token-fijo"
      }
    }
  }
}

Comandos MCP desde CLI

OpenCode incluye comandos para gestionar la autenticación y el estado de los servidores MCP:

# Autenticar con un servidor MCP remoto
opencode mcp auth mi-remote

# Listar todos los servidores MCP configurados
opencode mcp list

# Cerrar sesión de un servidor MCP
opencode mcp logout mi-remote

El comando mcp list muestra el estado de cada servidor: si está activo, cuántas herramientas expone y si la autenticación es válida. Es la primera herramienta de diagnóstico cuando un servidor MCP no funciona como esperas.

Controlar Herramientas MCP

Cada servidor MCP expone una o más herramientas. OpenCode te permite controlar cuáles están habilitadas usando patrones glob en la configuración de tools. Este control es fundamental para mantener el consumo de tokens bajo control.

Control global

{
  "tools": {
    "mi-mcp*": false,
    "mi-mcp_herramienta_especifica": true
  }
}

En este ejemplo, se deshabilitan todas las herramientas del servidor mi-mcp excepto mi-mcp_herramienta_especifica. Los patrones glob (*) permiten filtrar herramientas por prefijo.

Control por agente

Puedes deshabilitar MCP tools globalmente y habilitarlos solo para agentes específicos. Esto es una herramienta poderosa para crear agentes especializados:

{
  "agent": {
    "default": {
      "tools": {
        "playwright*": false,
        "sentry*": false
      }
    },
    "tester": {
      "tools": {
        "playwright*": true
      }
    },
    "debugger": {
      "tools": {
        "sentry*": true
      }
    }
  }
}

En este ejemplo:

Esta separación mantiene el contexto limpio para cada agente, reduciendo el consumo de tokens y mejorando la calidad de las respuestas.

Ejemplos de Servidores Populares

Sentry — Monitoreo de errores

{
  "mcp": {
    "sentry": {
      "type": "local",
      "command": ["npx", "-y", "@sentry/mcp-server"],
      "environment": {
        "SENTRY_AUTH_TOKEN": "tu-token"
      }
    }
  }
}

Permite al agente interactuar directamente con Sentry: consultar proyectos, listar issues recientes, ver stack traces completos y analizar patrones de errores. Es especialmente útil cuando estás debuggeando un problema reportado en producción — puedes pedirle al agente que busque el error en Sentry, analice el stack trace y proponga una corrección, todo en una sola conversación.

Context7 — Documentación actualizada

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@context7/mcp"]
    }
  }
}

Da acceso al agente a documentación actualizada de librerías y frameworks. Esto es crítico porque los modelos de lenguaje tienen un corte de conocimiento y pueden generar código con APIs obsoletas. Con Context7, el agente puede buscar la documentación real y actual antes de generar código.

Grep by Vercel — Búsqueda de código

{
  "mcp": {
    "grep": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic-ai/grep-mcp"],
      "environment": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Permite buscar código en repositorios de GitHub. Es útil cuando necesitas ver cómo otros proyectos resuelven un problema similar, buscar patrones de uso de una librería o encontrar ejemplos de implementación.

Playwright — Automatización del navegador

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"]
    }
  }
}

Permite al agente interactuar con páginas web: navegar, hacer click, llenar formularios, tomar capturas de pantalla y ejecutar tests E2E. Combinado con el agente tester, se convierte en una herramienta potente para testing automatizado.

Filesystem — Acceso a directorios específicos

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/ruta/a/directorio"]
    }
  }
}

Si necesitas dar acceso al agente a directorios fuera del proyecto actual, este servidor MCP proporciona acceso controlado al sistema de archivos.

Limpieza de Procesos MCP (v1.2.16)

A partir de v1.2.16, OpenCode mata automáticamente procesos MCP huérfanos al cerrar la sesión. Anteriormente, si cerrabas OpenCode abruptamente (Ctrl+C, cierre de terminal), los procesos de servidores MCP locales podían quedar corriendo en segundo plano, consumiendo recursos.

Además, OpenCode expone la variable de entorno OPENCODE_PID durante el shutdown, lo que permite a los servidores MCP detectar cuándo el proceso padre está terminando y realizar su propia limpieza de forma ordenada.

Si sospechas que hay procesos MCP huérfanos de sesiones anteriores, puedes verificarlo con:

# Buscar procesos MCP corriendo
ps aux | grep mcp

# Matar procesos huérfanos si los hay
pkill -f "mcp-server"

Consideraciones de Rendimiento y Tokens

Este es el punto más importante de todo el capítulo: los MCP servers consumen tokens del contexto.

Cada servidor MCP expone herramientas que el modelo necesita entender. Las definiciones de estas herramientas (nombre, descripción, parámetros, tipos) se incluyen en cada petición al modelo. Un servidor MCP con 10 herramientas puede añadir fácilmente 2,000-5,000 tokens al contexto de cada mensaje.

flowchart TD
    A[Contexto total del modelo] --> B[Tu prompt]
    A --> C[Historial de conversación]
    A --> D[Definiciones de herramientas built-in]
    A --> E[Definiciones de herramientas MCP]
    
    E --> F[Servidor 1: ~1000 tokens]
    E --> G[Servidor 2: ~2000 tokens]
    E --> H[Servidor 3: ~3000 tokens]
    
    style E fill:#ffcdd2

Recomendaciones para mantener el consumo bajo control:

La clave es encontrar el balance entre funcionalidad y eficiencia en el uso del contexto. Empieza con pocos servidores MCP y ve añadiendo según los necesites.

Crear tu Propio Servidor MCP

Si tienes una herramienta interna que quieres exponer como MCP, puedes crear un servidor usando el SDK oficial:

npx @modelcontextprotocol/create-server mi-servidor

Esto genera un scaffold con la estructura básica para implementar un servidor MCP en TypeScript. El servidor debe implementar el protocolo de descubrimiento de herramientas y los handlers para cada herramienta que expone.

Los servidores MCP personalizados son útiles para:

Resumen de Configuración Rápida

NecesidadServidorConfiguración
Monitoreo de erroresSentry@sentry/mcp-server + SENTRY_AUTH_TOKEN
Documentación actualizadaContext7@context7/mcp (sin config extra)
Búsqueda de códigoGrep@anthropic-ai/grep-mcp + GITHUB_TOKEN
Testing E2EPlaywright@playwright/mcp (sin config extra)
Acceso a archivosFilesystem@modelcontextprotocol/server-filesystem + ruta

Siguiente: Capitulo 13: Agent Skills —>

← Volver al listado de tecnologías ← Índice de OpenCode