Servidores MCP

Adicione ferramentas MCP locais e remotas.

Você pode adicionar ferramentas externas ao opencode usando o Model Context Protocol, ou MCP. O opencode suporta servidores locais e remotos.

Uma vez adicionadas, as ferramentas MCP estão automaticamente disponíveis para o LLM juntamente com as ferramentas integradas.

Avisos

Quando você usa um servidor MCP, ele adiciona ao contexto. Isso pode rapidamente se acumular se você tiver muitas ferramentas. Portanto, 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 em sua Configuração do opencode sob mcp. Adicione cada MCP com um nome único. Você pode se referir a esse MCP pelo nome ao solicitar ao 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 de sua configuração.

As organizações podem fornecer servidores MCP padrão através de 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
    }
  }
}

Os valores da sua configuração local substituem 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",
      // Or ["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.

{
  "$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.

Opção	Tipo	Requerido	Descrição
`type`	String	S	Tipo de conexão do servidor MCP, deve ser `"local"`.
`command`	Array	S	Comando e argumentos para executar o servidor MCP.
`environment`	Object		Variáveis de ambiente a serem definidas ao executar o servidor.
`enabled`	Boolean		Habilitar ou desabilitar o servidor MCP na inicialização.
`timeout`	Number		Tempo limite em ms para buscar ferramentas do servidor MCP. O padrão é 5000 (5 segundos).

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

Opção	Tipo	Requerido	Descrição
`type`	String	S	Tipo de conexão do servidor MCP, deve ser `"remote"`.
`url`	String	S	URL do servidor MCP remoto.
`enabled`	Boolean		Habilitar ou desabilitar o servidor MCP na inicialização.
`headers`	Object		Cabeçalhos a serem enviados com a solicitação.
`oauth`	Object		Configuração de autenticação OAuth. Veja a seção OAuth abaixo.
`timeout`	Number		Tempo limite em ms para buscar ferramentas do servidor MCP. O padrão é 5000 (5 segundos).

OAuth

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

Detectar a resposta 401 e iniciar o fluxo OAuth
Usar Registro Dinâmico de Cliente (RFC 7591) se suportado pelo servidor
Armazenar tokens de forma segura para futuras solicitações

Automático

Para a maioria dos servidores MCP habilitados para OAuth, nenhuma configuração especial é necessária. Basta configurar 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 quando tentar usá-lo pela primeira vez. Se não, você pode iniciar manualmente o fluxo 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 iniciar manualmente a autenticação 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. Após você autorizar, o opencode armazenará os tokens de forma segura 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

Opção	Tipo	Descrição
`oauth`	Object \| false	Objeto de configuração OAuth, ou `false` para desabilitar a detecção automática de OAuth.
`clientId`	String	ID do cliente OAuth. Se não fornecido, o registro dinâmico do cliente será tentado.
`clientSecret`	String	Segredo do cliente OAuth, se necessário pelo servidor de autorização.
`scope`	String	Escopos OAuth a serem solicitados durante a autorização.

Depuração

Se um servidor MCP remoto estiver falhando na autenticação, 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 de autenticação atual, testa a conectividade HTTP e tenta o fluxo de descoberta OAuth.

Gerenciar

Seus MCPs estão disponíveis como ferramentas no opencode, juntamente com ferramentas integradas. Portanto, 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ê tiver um grande número de servidores MCP, pode querer habilitá-los apenas por agente e desabilitá-los globalmente. Para fazer isso:

Desabilite-o como uma ferramenta globalmente.
Em sua configuração 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 regex globbing:

* 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

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 Sentry para interagir com seus projetos e problemas 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 o opencode à sua conta do Sentry.

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

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

Context7

Adicione o servidor MCP Context7 para pesquisar através de documentos.

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

Se você se inscreveu para uma conta gratuita, pode usar sua chave de 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 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 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 Grep by Vercel servidor MCP para pesquisar através de 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

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.