À medida que o seu fluxo de trabalho com o OpenCode evolui, tarefas repetitivas como revisão de código, geração de testes e consulta a dados externos passam a exigir mais do que apenas prompts manuais no terminal. É exatamente aqui que o OpenCode demonstra o seu maior diferencial: permitindo especializar subagentes dedicados e conectar a ferramenta a qualquer ecossistema externo através do MCP (Model Context Protocol).
Neste guia avançado, você aprenderá a configurar agentes com papéis específicos no seu projeto e a utilizar o protocolo MCP para conectar o OpenCode a bancos de dados, APIs e ferramentas de terceiros com total segurança e previsibilidade.
Visão geral: Agente Padrão vs. Agente Personalizado vs. MCP
Para escolher a abordagem ideal em cada cenário, consulte a tabela comparativa de referência rápida abaixo:
| Recurso | O que faz? | Quando utilizar? |
| Agente Padrão | Executa comandos genéricos de edição e análise de código | Tarefas do dia a dia, refatorações pontuais e dúvidas diretas |
| Agente Personalizado | Focado em um papel restrito (ex: Revisor, Testador) | Para impor regras rígidas de segurança ou escopo em fluxos específicos |
| MCP (Context Protocol) | Conecta a IA a ferramentas e dados externos (BD, GitHub, APIs) | Quando o agente precisa de contexto em tempo real do ambiente externo |
Estrutura base de configuração: opencode.json
Tanto a criação de subagentes quanto a adição de servidores MCP são declaradas diretamente no seu arquivo opencode.json (seja no nível global em ~/.config/opencode/ ou na raiz do seu projeto):
JSON
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"reviewer": {
"mode": "subagent",
"prompt": "Você é um revisor de código focado em segurança e padrões TypeScript. Aponte falhas de arquitetura, mas não edite arquivos.",
"permission": {
"edit": "deny",
"bash": "ask"
}
}
},
"mcp": {
"postgres": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
}
}
}
Criando Agentes Personalizados (Custom Agents)
Agentes personalizados funcionam como especialistas dedicados dentro da sua equipe virtual de desenvolvimento. Em vez de dar autonomia irrestrita ao modelo padrão, você cria perfis com instruções de sistema (System Prompts) e matrizes de permissão rígidas.
Exemplo 1: O Agente Auditor de Segurança (security-auditor)
Este agente analisa o código em busca de vulnerabilidades, mas está estritamente bloqueado de alterar qualquer arquivo ou executar comandos de shell:
JSON
"agent": {
"security-auditor": {
"mode": "subagent",
"prompt": "Examine as alterações recentes em busca de brechas de segurança (OWASP Top 10). Liste os problemas encontrados de forma objetiva e sugira correções.",
"permission": {
"edit": "deny",
"bash": "deny"
}
}
}
Como invocar um subagente no terminal
Dentro da sessão interativa do OpenCode, você pode direcionar a tarefa diretamente ao subagente criado usando a menção @:
Bash
@security-auditor analise a lógica de autenticação na pasta src/auth/
O que é e como funciona o MCP (Model Context Protocol)?
O Model Context Protocol (MCP) é um padrão aberto que permite que ferramentas de IA interajam de forma padronizada com sistemas externos. Pense no MCP como um “plugue de tomada universal”: o OpenCode não precisa saber como acessar cada banco de dados ou API do mercado; ele apenas conversa com o servidor MCP correspondente.
$$\text{OpenCode (Agente)} \iff \text{Protocolo MCP} \iff \begin{cases} \text{Banco de Dados (PostgreSQL / SQLite)} \\ \text{APIs Externas (GitHub / Sentry / Figma)} \\ \text{Sistemas de Arquivos e Documentação} \end{cases}$$
Conectando um banco de dados via MCP
Com um servidor MCP de banco de dados configurado no seu opencode.json, o agente ganha a capacidade de consultar schemas e tabelas em tempo real para criar migrations perfeitas:
Bash
opencode "analise a tabela 'users' no banco de dados via MCP e crie a migration necessária para adicionar o campo 'avatar_url'"
Segurança e boas práticas na automação avançada
- Nunca exponha credenciais no repositório: Sempre utilize variáveis de ambiente (ex:
${DATABASE_URL}) no arquivoopencode.jsone certifique-se de que o arquivo.envesteja listado no seu.gitignore. - Aplique o Princípio do Menor Privilégio: Subagentes cujo foco é apenas auditoria, revisão ou leitura de documentação devem ser configurados com
"edit": "deny". - Mantenha a aprovação humana para ações críticas: Para escrita em bancos de dados ou execução de scripts no terminal, mantenha a permissão configurada como
"ask".
Perguntas Frequentes (FAQ)
O uso de servidores MCP aumenta o consumo de tokens?
Sim. O protocolo MCP injeta a definição das ferramentas disponíveis no contexto de todas as mensagens. Conectar múltiplos servidores MCP simultâneos pode inflar o prompt do sistema e aumentar o consumo de tokens. Ative apenas os servidores necessários para o projeto atual.
Onde encontro servidores MCP prontos para usar?
A comunidade mantém um ecossistema ativo de servidores MCP open-source para ferramentas populares como PostgreSQL, GitHub, Google Drive, Slack, Brave Search e sistemas de arquivos locais.
Posso criar agentes personalizados no nível global?
Sim. Se você colocar as definições no arquivo ~/.config/opencode/opencode.json, os subagentes e servidores MCP estarão disponíveis automaticamente em todos os seus projetos locais.
Conclusão
A combinação de Agentes Personalizados com o Model Context Protocol (MCP) eleva o OpenCode de um simples assistente de código no terminal para um verdadeiro hub de automação e engenharia de software. Ao definir papéis claros e conectar suas ferramentas externas de dados, você constrói um ambiente previsível, seguro e incomparavelmente mais rápido.
O que vem a seguir: No décimo e último artigo da nossa série, encerraremos com chave de ouro: O guia definitivo do fluxo de trabalho assistido por IA com OpenCode, reunindo todas as peças do básico ao avançado em um grande estudo de caso prático do mundo real.
Você já utiliza o MCP ou criou algum subagente específico no seu fluxo de trabalho? Conte para a gente nos comentários abaixo!