↓ Ir al contenido
Inicio
  1. Posts/

Conectar OpenCode con GitHub MCP Server

·6 mins
Rafael Fernandez
Autor
Rafael Fernandez
Matemáticas, programación y cosas de la vida
Tabla de contenido

How-to desde cero (si empiezas de 0)
#

Si nunca conectaste OpenCode con GitHub MCP, esta es la ruta completa antes de entrar en el debug fino.

1) Instalar OpenCode
#

La forma mas directa:

curl -fsSL https://opencode.ai/install | bash

Alternativa con npm:

npm install -g opencode-ai

2) Crear un PAT en GitHub
#

Para este flujo uso PAT fine-grained.

Ruta directa para crear token:

3) Dar permisos al PAT (minimo recomendado)
#

Depende de que quieras hacer con el MCP, pero para un uso habitual de lectura/escritura sobre repos y PRs, empieza con:

  • Metadata: Read-only
  • Contents: Read and write
  • Pull requests: Read and write
  • Issues: Read and write

Si solo quieres lectura, reduce a read-only donde aplique. Si luego necesitas mas (por ejemplo actions/checks), amplias permisos con criterio de minimo privilegio.

4) Guardar el token en archivo secreto
#

Crear carpeta y archivo:

mkdir -p ~/.config/opencode/.secrets
chmod 700 ~/.config/opencode/.secrets
printf 'github_pat_xxxxxxxxxxxxxxxxxxxx' > ~/.config/opencode/.secrets/github-pat
chmod 600 ~/.config/opencode/.secrets/github-pat

5) Configurar OpenCode con GitHub MCP remoto
#

En ~/.config/opencode/opencode.json agrega:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {file:~/.config/opencode/.secrets/github-pat}"
      }
    }
  }
}

6) Verificar que realmente funciona
# 

opencode mcp list
opencode mcp debug github --log-level DEBUG

Y en OpenCode prueba una accion real:

List open pull requests in owner/repo using github mcp tools.

Si esto responde bien, ya tienes la base funcionando y puedes pasar al resto del post para entender por que falla en algunos entornos y como evitar esos tropiezos.

Por que existe este post
#

Este post nace de una tarde de frustracion real.

Yo tenia OpenCode funcionando bien con otros MCP, pero con GitHub MCP no habia manera: no aparecian herramientas de GitHub y la integracion parecia rota.

Lo raro era esto: la documentacion de OpenCode explica MCP en general, y la de GitHub MCP explica hosts soportados, pero no encontraba un “haz esto asi” para OpenCode + servidor remoto de GitHub en un mismo flujo claro.

Mis errores eran siempre los mismos:

  • 401 Unauthorized (No access token was provided in this request)
  • Incompatible auth server: does not support dynamic client registration

Si llegaste aqui por esos mensajes, estas en el lugar correcto.

Por que queria GitHub MCP dentro de OpenCode
#

Para mi, el valor de GitHub MCP no es solo “tener mas herramientas”. Es reducir friccion mental.

conectar-opencode-con-github-mcp-server-img-8.png

Cuando estoy escribiendo o revisando codigo en OpenCode, poder leer issues, abrir PRs, revisar comentarios o consultar estado de checks sin salir del mismo flujo cambia mucho la experiencia. Pasas de “copiar contexto entre terminal, navegador y editor” a “resolver todo en una sola conversacion con contexto tecnico”.

Y en tareas reales de equipo se nota todavia mas: seguir una issue hasta PR, responder feedback, o validar un diff grande se vuelve mas directo porque el agente tiene acceso a GitHub en el mismo hilo donde ya entiende tu objetivo.

Version corta
#

Para esta integracion, un enfoque practico y estable es:

  1. Usar el endpoint remoto de GitHub MCP: https://api.githubcopilot.com/mcp/
  2. Usar un GitHub PAT (mejor fine-grained)
  3. Enviarlo en el header Authorization: Bearer ...
  4. Configurar "oauth": false para ese servidor MCP en OpenCode

Ese ultimo punto es la clave del asunto cuando no estas usando OAuth pre-registrado.

Configuracion que funciona
#

Abre tu configuracion global de OpenCode:

  • ~/.config/opencode/opencode.json

Y agrega (o actualiza) este bloque:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {file:~/.config/opencode/.secrets/github-pat}"
      }
    }
  }
}

Luego crea el archivo de secreto y coloca ahi el token:

  • ~/.config/opencode/.secrets/github-pat

Contenido del archivo:

github_pat_xxxxxxxxxxxxxxxxxxxx

Eso fue exactamente lo que desbloqueo mi configuracion.

Y aqui una decision personal que para mi fue clave: no uso variables globales para cada token o cada conexion.

Podria exportar GITHUB_TOKEN, SENTRY_TOKEN, X_API_KEY, etc, pero no me gusta llenar mi entorno global con secretos que no necesito en todas las sesiones. Prefiero usar {file:...} apuntando a un secreto concreto por integracion.

En mi opinion, ese enfoque es mas recomendable porque:

  • evita contaminar el entorno global con demasiados secretos,
  • reduce errores al mezclar variables entre proyectos,
  • y te obliga a tener una estructura de secretos mas clara y controlada.

Por que funciona
#

OpenCode soporta OAuth automatico para servidores MCP remotos y, por defecto, puede intentar dynamic client registration.

Desde GitHub indicaron que no planean soportar dynamic client registration en este flujo, asi que el cliente puede fallar durante la negociacion OAuth segun el host.

Al definir:

"oauth": false

fuerzas autenticacion por header Bearer y evitas ese camino de negociacion OAuth.

Traducido a lenguaje de trinchera: en lugar de esperar que OpenCode y el server cierren un flujo OAuth automatico que aqui no cuadra, le dices “usa este token en este header y listo”.

Detalles que te pueden ahorrar horas
#

1) La sintaxis de variables importa
#

En OpenCode usa:

  • {env:MI_VAR}
  • {file:ruta/al/secreto}

No uses ${env:MI_VAR}.

Parece un detalle minimo, pero ese detalle rompe toda la autenticacion.

2) El debug puede confundir
#

Puede que opencode mcp debug ... muestre advertencias relacionadas con OAuth incluso cuando las herramientas MCP ya funcionan en la TUI. Esto se reporto varias veces en la issue.

Valida siempre comportamiento real, no solo salida de debug.

3) No pongas el token inline
#

Evita meter PATs en JSON plano. Con {file:...} queda mas limpio y mas seguro.

Es una decision pequena que evita muchos problemas despues (copias, leaks, commits accidentales).

Y por la misma razon, tambien prefiero archivo a variable global: menos superficie, menos ruido, mas control.

Verificacion rapida
#

Ejecuta:

opencode mcp list
opencode mcp debug github --log-level DEBUG

Luego, desde OpenCode, pide una accion de GitHub que use herramientas MCP, por ejemplo:

List open pull requests in owner/repo using github mcp tools.

Si las herramientas aparecen y la llamada se ejecuta, ya quedo configurado.

Yo use ese criterio: menos teoria, mas “funciona o no funciona” con una accion real sobre repos.

PAT vs OAuth app (nota de seguridad)
#

Esta guia usa PAT porque es el camino mas rapido y el que la mayoria prueba primero.

Para entornos mas maduros, OAuth app puede ser mejor segun requisitos de seguridad y politicas de organizacion. Pero si tu objetivo inmediato es hacerlo funcionar hoy en OpenCode, la ruta PAT + oauth: false es la solucion practica.

Mi recomendacion: empieza con PAT para validar flujo extremo a extremo, y luego endurece el modelo de autenticacion cuando ya tengas la integracion estable.

Referencias
#

Si la documentacion oficial agrega una guia explicita para OpenCode, mejor para todos. Mientras tanto, esta fue la ruta que me funciono en la practica y que puedes reproducir en minutos.