DevOpsApril 6, 20267 min read2 views

OpenCode: Configuración avanzada y servidores MCP

El sistema de configuración de OpenCode

OpenCode utiliza un sistema de configuración jerárquico por capas donde múltiples archivos se fusionan en orden de prioridad. Esto te permite tener una configuración global personal, una por proyecto, e incluso una organizacional remota.

El orden de prioridad (de mayor a menor) es:

Proyecto: opencode.json en la raíz del proyecto
Variable de entorno: OPENCODE_CONFIG apuntando a un archivo personalizado
Global: ~/.config/opencode/opencode.json
Organizacional: .well-known/opencode (remoto)
Managed settings: Configuraciones forzadas por administradores

Fuente: OpenCode — GitHub Repository

Dato clave: Las configuraciones se fusionan, no se reemplazan. La configuración del proyecto extiende la global, permitiéndote sobrescribir solo lo que necesitas.

Configuración completa del proyecto

Veamos un opencode.json completo con todas las opciones principales:

1{
2  "model": "anthropic/claude-sonnet-4-5",
3  "small_model": "anthropic/claude-haiku-4-5",
4  "server": {
5    "port": 4096,
6    "hostname": "localhost",
7    "cors": true
8  },
9  "permission": {
10    "ask": "allow",
11    "skill": {
12      "*": "allow",
13      "internal-*": "deny"
14    }
15  },
16  "agents": {
17    "reviewer": {
18      "prompt": ".opencode/agents/reviewer.md",
19      "model": "anthropic/claude-opus-4-1",
20      "tools": {
21        "bash": false,
22        "edit": false,
23        "read": true
24      }
25    }
26  }
27}

Variables de entorno en la configuración

OpenCode soporta sustitución de variables, lo que es ideal para no hardcodear secrets:

1{
2  "model": "{env:OPENCODE_MODEL}",
3  "provider": {
4    "anthropic": {
5      "options": {
6        "apiKey": "{env:ANTHROPIC_API_KEY}",
7        "baseURL": "{env:ANTHROPIC_BASE_URL}"
8      }
9    }
10  },
11  "instructions": "{file:.opencode/instructions.md}"
12}

Sintaxis	Descripción	Ejemplo
`{env:VARIABLE}`	Lee una variable de entorno	`{env:ANTHROPIC_API_KEY}`
`{file:ruta}`	Incluye el contenido de un archivo	`{file:.opencode/rules.md}`

Configuración de proveedores de IA

Una de las mayores ventajas de OpenCode es su compatibilidad con más de 75 proveedores. Aquí te mostramos cómo configurar los principales:

Anthropic (Claude)

1# Variable de entorno
2export ANTHROPIC_API_KEY="sk-ant-api03-..."
3
4# O en opencode.json

1{
2  "model": "anthropic/claude-sonnet-4-5",
3  "provider": {
4    "anthropic": {
5      "options": {
6        "baseURL": "https://api.anthropic.com/v1"
7      }
8    }
9  }
10}

OpenAI

1export OPENAI_API_KEY="sk-..."

1{
2  "model": "openai/gpt-4o"
3}

Google Gemini

1export GOOGLE_API_KEY="AIza..."

1{
2  "model": "google/gemini-2.5-pro"
3}

Ollama (modelos locales)

1# Primero, instala y ejecuta Ollama
2ollama serve
3ollama pull llama3.1:70b

1{
2  "model": "ollama/llama3.1:70b",
3  "provider": {
4    "ollama": {
5      "options": {
6        "baseURL": "http://localhost:11434"
7      }
8    }
9  }
10}

💡 Tip: Usa Ollama para tareas que no requieran el máximo rendimiento (formateo, documentación, refactoring simple). Reserva Claude o GPT-4 para tareas complejas de arquitectura y debugging.

AWS Bedrock

1export AWS_ACCESS_KEY_ID="AKIA..."
2export AWS_SECRET_ACCESS_KEY="..."
3export AWS_REGION="us-east-1"

1{
2  "model": "bedrock/anthropic.claude-sonnet-4-5",
3  "provider": {
4    "bedrock": {
5      "options": {
6        "region": "us-east-1"
7      }
8    }
9  }
10}

Sistema de permisos

OpenCode tiene un sistema de permisos granular que controla qué pueden hacer los agentes y Skills:

1{
2  "permission": {
3    "ask": "allow",
4    "skill": {
5      "*": "allow",
6      "dangerous-*": "deny"
7    },
8    "mcp": {
9      "filesystem": "allow",
10      "github": "ask"
11    }
12  }
13}

Valor	Comportamiento
`allow`	Permite la acción sin preguntar
`deny`	Bloquea la acción silenciosamente
`ask`	Solicita confirmación al usuario antes de ejecutar

¿Qué es MCP (Model Context Protocol)?

MCP es un protocolo estándar abierto que permite a los agentes de IA conectarse con herramientas y fuentes de datos externas. Piensa en MCP como un USB universal para IA: una interfaz estandarizada que permite que cualquier herramienta se conecte con cualquier agente.

OpenCode nueva sesión mostrando servidores MCP disponibles

Fuente: OpenCode — GitHub Repository

Con MCP, OpenCode puede:

Consultar bases de datos directamente
Interactuar con APIs de GitHub, GitLab, Jira
Leer y escribir en sistemas de archivos remotos
Enviar mensajes a Slack o Teams
Acceder a servicios de observabilidad (Grafana, Datadog)
Conectar con cualquier servicio que implemente el protocolo

Configurando servidores MCP locales

Los servidores MCP locales se ejecutan como procesos en tu máquina. Son ideales para herramientas que necesitan acceso al sistema de archivos o a servicios locales.

Servidor de sistema de archivos

1{
2  "mcp": {
3    "filesystem": {
4      "type": "local",
5      "command": "npx",
6      "args": [
7        "@modelcontextprotocol/server-filesystem",
8        "/home/user/documents",
9        "/home/user/projects"
10      ]
11    }
12  }
13}

Esto le da a OpenCode acceso controlado a directorios específicos fuera del proyecto actual.

Servidor de PostgreSQL

1{
2  "mcp": {
3    "postgres": {
4      "type": "local",
5      "command": "npx",
6      "args": [
7        "@modelcontextprotocol/server-postgres",
8        "{env:DATABASE_URL}"
9      ]
10    }
11  }
12}

1# Ejemplo de interacción con la base de datos
2> ¿Cuántos usuarios se registraron esta semana?
3
4# OpenCode ejecuta via MCP:
5# SELECT COUNT(*) FROM users WHERE created_at >= NOW() - INTERVAL '7 days';
6# Resultado: 142 usuarios

Servidor de GitHub

1{
2  "mcp": {
3    "github": {
4      "type": "local",
5      "command": "npx",
6      "args": [
7        "@modelcontextprotocol/server-github"
8      ],
9      "env": {
10        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
11      }
12    }
13  }
14}

1# Ejemplo: trabajar con issues de GitHub
2> Lista los issues abiertos con label "bug" y asígname el más antiguo
3
4# OpenCode interactúa con la API de GitHub vía MCP
5# y ejecuta las acciones necesarias

Configurando servidores MCP remotos

Los servidores remotos se ejecutan en la nube y OpenCode se conecta a ellos via HTTP. Son ideales para servicios compartidos por todo el equipo.

1{
2  "mcp": {
3    "company-tools": {
4      "type": "remote",
5      "url": "https://mcp.mi-empresa.com/tools"
6    },
7    "grafana": {
8      "type": "remote",
9      "url": "https://mcp.mi-empresa.com/grafana",
10      "headers": {
11        "Authorization": "Bearer {env:GRAFANA_TOKEN}"
12      }
13    }
14  }
15}

Vista de servidores MCP configurados en OpenCode

Fuente: OpenCode — GitHub Repository

Autenticación automática: OpenCode maneja OAuth automáticamente usando Dynamic Client Registration (RFC 7591). Si un servidor MCP remoto responde con 401, OpenCode inicia el flujo de autenticación transparentemente.

LSP: inteligencia de código nativa

OpenCode incluye soporte nativo para Language Server Protocol (LSP), proporcionando inteligencia de código real — no solo sugerencias basadas en texto. Soporta más de 20 lenguajes con descarga automática de servidores.

Capacidades que el LSP le da a OpenCode:

Diagnósticos: Errores y warnings en tiempo real
Hover info: Tipos y documentación al inspeccionar símbolos
Go to definition: Navegar al código fuente de funciones importadas
Find references: Encontrar todos los usos de una función o variable
Autocompletado: Sugerencias basadas en el contexto real del proyecto

1{
2  "lsp": {
3    "typescript": true,
4    "python": true,
5    "go": true,
6    "rust": true
7  }
8}

Para desactivar la descarga automática de servidores LSP:

1# Desactivar globalmente
2export OPENCODE_DISABLE_LSP_DOWNLOAD=1
3
4# O por agente en opencode.json

1{
2  "agents": {
3    "quick-chat": {
4      "tools": {
5        "lsp": false
6      }
7    }
8  }
9}

Snapshots y sistema de undo/redo

OpenCode toma snapshots automáticos de tus archivos antes de cada modificación. Esto te permite revertir cambios de forma segura:

1# Dentro de la TUI
2/undo    # Revierte el último cambio
3/redo    # Restaura el cambio revertido
4
5# Ver historial de snapshots
6opencode session list

Los snapshots están habilitados por defecto. Para desactivarlos (no recomendado):

1{
2  "snapshot": {
3    "enabled": false
4  }
5}

⚠️ Atención: Desactivar los snapshots elimina la posibilidad de hacer undo/redo. Solo hazlo si tienes un sistema de control de versiones robusto y haces commits frecuentes.

Formateadores personalizados

Define comandos de formateo que OpenCode ejecutará automáticamente después de editar archivos:

1{
2  "format": {
3    "*.ts": "npx prettier --write",
4    "*.tsx": "npx prettier --write",
5    "*.py": "black",
6    "*.go": "gofmt -w",
7    "*.rs": "rustfmt"
8  }
9}

Ejemplo completo: configuración para un equipo

Veamos una configuración real para un equipo de desarrollo full-stack:

1{
2  "model": "anthropic/claude-sonnet-4-5",
3  "small_model": "anthropic/claude-haiku-4-5",
4
5  "server": {
6    "port": 4096,
7    "hostname": "localhost"
8  },
9
10  "permission": {
11    "ask": "allow",
12    "mcp": {
13      "postgres": "ask",
14      "github": "allow",
15      "slack": "ask"
16    }
17  },
18
19  "mcp": {
20    "postgres": {
21      "type": "local",
22      "command": "npx",
23      "args": ["@modelcontextprotocol/server-postgres", "{env:DATABASE_URL}"]
24    },
25    "github": {
26      "type": "local",
27      "command": "npx",
28      "args": ["@modelcontextprotocol/server-github"],
29      "env": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" }
30    },
31    "slack": {
32      "type": "remote",
33      "url": "https://mcp.empresa.com/slack"
34    }
35  },
36
37  "agents": {
38    "reviewer": {
39      "prompt": ".opencode/agents/reviewer.md",
40      "model": "anthropic/claude-opus-4-1",
41      "tools": { "bash": false, "edit": false, "read": true }
42    },
43    "quick": {
44      "model": "anthropic/claude-haiku-4-5",
45      "tools": { "bash": true, "edit": true, "lsp": false }
46    }
47  },
48
49  "format": {
50    "*.ts": "npx prettier --write",
51    "*.tsx": "npx prettier --write",
52    "*.css": "npx prettier --write"
53  },
54
55  "instructions": "{file:.opencode/instructions.md}"
56}

Variables de entorno avanzadas

OpenCode ofrece más de 40 variables de entorno para personalización. Aquí las más útiles:

Variable	Descripción	Ejemplo
`OPENCODE_CONFIG`	Ruta a un archivo de configuración personalizado	`/etc/opencode/team.json`
`OPENCODE_CONFIG_DIR`	Directorio de configuración personalizado	`~/.my-opencode`
`OPENCODE_DISABLE_LSP_DOWNLOAD`	Desactiva la descarga automática de LSP servers	`1`
`OPENCODE_INSTALL_DIR`	Directorio de instalación del binario	`~/.local/bin`
`ANTHROPIC_API_KEY`	API key de Anthropic	`sk-ant-...`
`OPENAI_API_KEY`	API key de OpenAI	`sk-...`

Conclusión

La configuración avanzada de OpenCode y los servidores MCP te permiten convertir un asistente de código genérico en una herramienta perfectamente adaptada a tu stack, tu equipo y tu flujo de trabajo. La clave está en:

Configuración por capas: Combina global + proyecto para máxima flexibilidad
MCP servers: Conecta OpenCode a tus herramientas existentes (DB, GitHub, Slack)
LSP nativo: Inteligencia de código real, no solo texto
Permisos granulares: Controla exactamente qué puede hacer cada agente
Variables de entorno: Nunca hardcodees secrets en la configuración

Con esta serie de tres artículos tienes todo lo necesario para instalar, personalizar y dominar OpenCode como tu asistente de código con IA de cabecera.

💡 Recurso: Consulta la documentación oficial en opencode.ai/docs y el repositorio en GitHub para mantenerte al día con las últimas funcionalidades.

Cristhian Villegas

Software Engineer specializing in Java, Spring Boot, Angular & AWS. Building scalable distributed systems with clean architecture.

GitHub LinkedIn Portfolio

Comments

No comments yet. Be the first!

April 6, 2026

Stay updated

Get notified when I publish new articles. No spam, unsubscribe anytime.

OpenCode: Configuración avanzada y servidores MCP

El sistema de configuración de OpenCode

Configuración completa del proyecto

Variables de entorno en la configuración

Configuración de proveedores de IA

Anthropic (Claude)

OpenAI

Google Gemini

Ollama (modelos locales)

AWS Bedrock

Sistema de permisos

¿Qué es MCP (Model Context Protocol)?

Configurando servidores MCP locales

Servidor de sistema de archivos

Servidor de PostgreSQL

Servidor de GitHub

Configurando servidores MCP remotos

LSP: inteligencia de código nativa

Snapshots y sistema de undo/redo

Formateadores personalizados

Ejemplo completo: configuración para un equipo

Variables de entorno avanzadas

Conclusión

Cristhian Villegas

Comments

Related Articles

OpenCode: Advanced Configuration and MCP Servers

OpenCode Skills and Custom Agents: A Practical Guide

Skills y Agentes personalizados en OpenCode: guía práctica

Stay updated