Servidores MCP

Adicione ferramentas MCP locais e remotas.

Você pode adicionar ferramentas externas ao OpenCode usando o Model Context Protocol, ou MCP. O OpenCode oferece suporte a servidores locais e remotos.

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

Ressalvas

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

Dica: Os servidores MCP adicionam ao seu contexto, então você quer ter cuidado com quais habilita.

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 Config do OpenCode (opens in a new tab) em mcp. Adicione cada MCP com um nome único. Você pode se referir a esse MCP pelo nome ao instruir 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 config.

Substituindo padrões remotos

Organizações podem fornecer servidores MCP padrão via o endpoint .well-known/opencode. Esses servidores podem estar desabilitados por padrão, permitindo que os usuários optem por aqueles de que precisam.

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

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

Os valores da sua config local substituem os padrões remotos. Veja precedência de config 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",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

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

Por exemplo, veja 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"
      }
    }
  }
}

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

Opções

OAuth

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

1. Detectar a resposta 401 e iniciar o fluxo OAuth
2. Usar Dynamic Client Registration (RFC 7591) se suportado pelo servidor
3. Armazenar os tokens com segurança para requisições futuras

Automático

Para a maioria dos servidores MCP com OAuth habilitado, 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, o OpenCode solicitará que você se autentique na primeira vez que tentar usá-lo. Se não, você pode acionar o fluxo manualmente com opencode mcp auth <server-name>.

Pré-registrado

Se você tiver 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"
      }
    }
  }
}

Autenticando

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

Autentique-se com um servidor MCP específico:

opencode mcp auth my-oauth-server

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

opencode mcp list

Remova credenciais armazenadas:

opencode mcp logout my-oauth-server

O comando mcp auth abrirá seu navegador para autorização. Depois que você autorizar, o OpenCode armazenará os tokens com segurança em ~/.local/share/opencode/mcp-auth.json.

Desabilitando OAuth

Se você quiser desabilitar o OAuth automático para um servidor (por exemplo, para servidores que usam chaves de API em vez disso), 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 de OAuth

Depuração

Se um servidor MCP remoto está falhando ao autenticar, você pode diagnosticar problemas com:

# View auth status for all OAuth-capable servers
opencode mcp auth list
 
# Debug connection and OAuth flow for a specific server
opencode mcp debug my-oauth-server

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

Gerenciar

Seus MCPs ficam disponíveis como ferramentas no OpenCode, junto às ferramentas integradas. Então você pode gerenciá-los através da config 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, talvez queira habilitá-los apenas por agente e desabilitá-los globalmente. Para fazer isso:

1. Desabilite-o como uma ferramenta globalmente.
2. Na sua config de agente , habilite o servidor MCP como uma 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 simples de globbing tipo regex:

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

Nota: As ferramentas de servidor MCP são registradas com o nome do servidor como prefixo, então, para desabilitar todas as ferramentas de um servidor, basta usar:

"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": {}
    }
  }
}

Depois de 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 o OpenCode à sua conta do Sentry.

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

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 na documentação.

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

Se você criou uma conta gratuita, pode usar sua chave de API e obter limites de taxa maiores.

{
  "$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 estamos assumindo 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

Como alternativa, 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 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 como 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

Como alternativa, 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.