Servidores MCP

Adicione ferramentas MCP locais e remotas.

Você pode adicionar ferramentas externas ao OpenCode usando o Model Context Protocol, ou MCP. OpenCode suporta tanto servidores locais quanto remotos.

Uma vez adicionadas, as ferramentas MCP ficam automaticamente disponíveis para o LLM junto com as ferramentas integradas.

Avisos

Quando você usa um servidor MCP, ele é adicionado ao contexto. Isso pode se acumular rapidamente se você tiver muitas ferramentas. Por isso, recomendamos ter cuidado com quais servidores MCP você usa.

Certos servidores MCP, como o servidor MCP do GitHub, tendem a adicionar muitos tokens e podem facilmente exceder o limite de contexto.

Habilitar

Você pode definir servidores MCP na sua Configuração do OpenCode em mcp. Adicione cada MCP com um nome único. Você pode se referir a esse MCP pelo nome ao fazer prompts para o LLM.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true,
    },
    "name-of-other-mcp-server": {
      // ...
    },
  },
}

Você também pode desabilitar um servidor definindo enabled como false. Isso é útil se você quiser desabilitar temporariamente um servidor sem removê-lo da sua configuração.

Sobrescrever padrões remotos

Organizações podem fornecer servidores MCP padrão através do seu endpoint .well-known/opencode. Esses servidores podem estar desabilitados por padrão, permitindo que os usuários optem pelos que precisam.

Para habilitar um servidor específico da configuração remota da sua organização, adicione-o à sua configuração local com enabled: true:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Seus valores de configuração local sobrescrevem os padrões remotos. Veja precedência de configuração para mais detalhes.

Local

Adicione servidores MCP locais usando type como "local" dentro do objeto MCP.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Ou ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

O comando é como o servidor MCP local é iniciado. Você também pode passar uma lista de variáveis de ambiente.

Por exemplo, aqui está como você pode adicionar o servidor MCP de teste @modelcontextprotocol/server-everything (opens in a new tab).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

E para usá-lo, posso adicionar use the mcp_everything tool aos meus prompts.

use the mcp_everything tool to add the number 3 and 4

Opções

Aqui estão todas as opções para configurar um servidor MCP local.

Remoto

Adicione servidores MCP remotos definindo type como "remote".

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

A url é a URL do servidor MCP remoto e com a opção headers você pode passar uma lista de cabeçalhos.

Opções

OAuth

OpenCode lida automaticamente com autenticação OAuth para servidores MCP remotos. Quando um servidor requer autenticação, OpenCode irá:

• Detectar a resposta 401 e iniciar o fluxo OAuth
• Usar Dynamic Client Registration (RFC 7591) se suportado pelo servidor
• Armazenar tokens de forma segura para requisições futuras

Automático

Para a maioria dos servidores MCP habilitados com OAuth, nenhuma configuração especial é necessária. Apenas configure o servidor remoto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Se o servidor requer autenticação, OpenCode irá solicitar que você se autentique quando tentar usá-lo pela primeira vez. Caso contrário, você pode acionar manualmente o fluxo com opencode mcp auth <server-name>.

Pré-registrado

Se você tem credenciais de cliente do provedor do servidor MCP, pode configurá-las:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Autenticação

Você pode acionar manualmente a autenticação ou gerenciar credenciais.

Autenticar com um servidor MCP específico:

opencode mcp auth my-oauth-server

Listar todos os servidores MCP e seu status de autenticação:

opencode mcp list

Remover credenciais armazenadas:

opencode mcp logout my-oauth-server

O comando mcp auth abrirá seu navegador para autorização. Após autorizar, OpenCode armazenará os tokens de forma segura em ~/.local/share/opencode/mcp-auth.json.

Desabilitar OAuth

Se você quiser desabilitar OAuth automático para um servidor (por exemplo, para servidores que usam chaves API), defina oauth como false:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Opções OAuth

Depuração

Se um servidor MCP remoto falhar ao autenticar, você pode diagnosticar problemas com:

# Ver status de autenticação para todos os servidores com OAuth
opencode mcp auth list
 
# Depurar conexão e fluxo OAuth para um servidor específico
opencode mcp debug my-oauth-server

O comando mcp debug mostra o status atual de autenticação, testa conectividade HTTP e tenta o fluxo de descoberta OAuth.

Gerenciar

Seus MCPs estão disponíveis como ferramentas no OpenCode, junto com as ferramentas integradas. Então você pode gerenciá-los através da configuração do OpenCode como qualquer outra ferramenta.

Global

Isso significa que você pode habilitá-los ou desabilitá-los globalmente.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false
  }
}

Também podemos usar um padrão glob para desabilitar todos os MCPs correspondentes.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false
  }
}

Aqui estamos usando o padrão glob my-mcp* para desabilitar todos os MCPs.

Por agente

Se você tem um grande número de servidores MCP, pode querer habilitá-los apenas por agente e desabilitá-los globalmente. Para fazer isso:

• Desabilite-o como ferramenta globalmente.
• Na sua configuração de agente, habilite o servidor MCP como ferramenta.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

Padrões glob

O padrão glob usa padrões de globbing regex simples:

• * corresponde a zero ou mais de qualquer caractere (por exemplo, "my-mcp*" corresponde a my-mcp_search, my-mcp_list, etc.)
• ? corresponde exatamente a um caractere
• Todos os outros caracteres correspondem literalmente

"mymcpservername_*": false

Exemplos

Abaixo estão exemplos de alguns servidores MCP comuns. Você pode enviar um PR se quiser documentar outros servidores.

Sentry

Adicione o servidor MCP do Sentry (opens in a new tab) para interagir com seus projetos e issues do Sentry.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Após adicionar a configuração, autentique-se com o Sentry:

opencode mcp auth sentry

Isso abrirá uma janela do navegador para completar o fluxo OAuth e conectar OpenCode à sua conta Sentry.

Uma vez autenticado, você pode usar as ferramentas do Sentry nos seus prompts para consultar issues, projetos e dados de erros.

Show me the latest unresolved issues in my project. use sentry

Context7

Adicione o servidor MCP do Context7 (opens in a new tab) para pesquisar documentação.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Se você se registrou para uma conta gratuita, pode usar sua chave API e obter limites de taxa mais altos.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

Aqui assumimos que você tem a variável de ambiente CONTEXT7_API_KEY definida.

Adicione use context7 aos seus prompts para usar o servidor MCP do Context7.

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

Alternativamente, você pode adicionar algo assim ao seu AGENTS.md.

When you need to search docs, use `context7` tools.

Grep by Vercel

Adicione o servidor MCP do Grep by Vercel (opens in a new tab) para pesquisar trechos de código no GitHub.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Como nomeamos nosso servidor MCP gh_grep, você pode adicionar use the gh_grep tool aos seus prompts para fazer o agente usá-lo.

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

Alternativamente, você pode adicionar algo assim ao seu AGENTS.md.

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.