CH 12 · Conecte-se ao Ecossistema MCP

Número de palavras~4.900 palavrasTempo~20 minPré-requisitoCH 03–05 já em execuçãoNívelReproduzível

Objetivo do capítulo

As ferramentas integradas do dsh (ler arquivos, executar comandos, pesquisar na web) bastam para o uso diário, mas o mundo lá fora está cheio de ferramentas dispersas — GitHub, bancos de dados, memória, navegadores, vários SaaS — elas não entram no seu Agent por conta própria. Este capítulo conecta o ecossistema MCP: primeiro explica o que é MCP, por que o dsh usa um "plugin" para conectar, depois monta na prática o servidor MCP do Firecrawl, para que o modelo possa chamar suas ferramentas como se fossem ferramentas nativas.

Primeiro entenda: o que é MCP

MCP (Model Context Protocol) é um protocolo aberto que resolve o problema geral de "como aplicações de IA se conectam a servidores externos de ferramentas". Você pode pensar no MCP como o USB-C do mundo das ferramentas: uma interface padrão, e dá para conectar qualquer dispositivo nele.

O ecossistema MCP já tem um grande conjunto de servidores MCP prontos:

Servidor MCP	O que faz
Sistema de arquivos	Lê/escreve subdiretórios (expõe um diretório local ao Agent)
GitHub	Cria issues, abre PRs, consulta repositórios
Banco de dados	Consulta vários bancos de dados
Memory	Acesso à memória de longo prazo (você verá de novo no CH 14)
Browser	Controla o navegador, faz scraping de páginas

O jeito de conectar MCP ao dsh está alinhado com seu estilo — um plugin: @deepseek-ai/dsh-mcp-client. O papel desse plugin oficial é puro: conectar todo servidor MCP declarado por você, e registrar as ferramentas que eles fornecem em ctx.tools (o registro de ferramentas que CH 11 mencionou), de modo que aos olhos do modelo elas não diferem em nada das ferramentas nativas. Isso mais uma vez confirma o "tudo é um plugin" do CH 08 — a integração com MCP não é exceção.

Alguns pontos que vale a pena saber de antemão:

• A nomenclatura de ferramentas tem dois níveis: primeiro há um servidor MCP (por exemplo Firecrawl), e abaixo dele há um lote de ferramentas (firecrawl_scrape faz scraping de página, firecrawl_search pesquisa páginas, firecrawl_map lista o sitemap...). Após conectadas, cada ferramenta aparece como mcp__<server-name>__<tool-name> — se o nome do servidor for firecrawl, sua ferramenta de scraping é mcp__firecrawl__firecrawl_scrape. Isso bate com o formato de nomenclatura do Claude Code e Codex. Servidores diferentes podem compartilhar nomes sem conflito (cada um tem seu próprio prefixo).
• Nenhum servidor é ativado por padrão: o fato de o plugin estar instalado é uma coisa; quais servidores conectar é completamente por conta da sua declaração. Sem configuração, ele não conecta nada. Uma vez declarado, o servidor conectará quando o dsh iniciar, e as ferramentas se registram na lista de ferramentas; quanto a qual rodada chama qual ferramenta, o modelo escolhe por conta própria conforme a tarefa atual — ele não chama todas as ferramentas a cada vez.
• Atualmente só faz ponte com "tools": além de "tools" (Tool, ações chamáveis), o protocolo MCP também tem outras duas capacidades — "Resources" (Resource, dados e arquivos somente-leitura) e templates de "Prompt" (Prompt). O plugin-ponte do dsh só traz por ora "tools"; resources e templates de prompt ainda não podem ser usados.
• Muitos servidores exigem autenticação: servidores MCP que se conectam a serviços reais, como GitHub e Firecrawl, geralmente precisam de uma API Key ou token. As chaves são passadas pelo campo headers na configuração (método HTTP), não coloque-as hardcoded no arquivo de configuração — a seção de configuração abaixo detalha isso.

Mãos à obra: conecte seu primeiro servidor MCP — Firecrawl

A seguir, o Firecrawl (um serviço real de scraping MCP, site do Firecrawl) conduz você. Seu servidor MCP fornece um lote de ferramentas web: firecrawl_scrape (faz scraping de uma única página), firecrawl_search (pesquisa na web), firecrawl_map (lista o sitemap), firecrawl_crawl (crawleia um site inteiro), firecrawl_extract (extrai campos estruturados), etc.

Passo 1: confirme que o plugin MCP Client está no lugar

Primeiro confirme se dsh-mcp-client está lá. Não precisa ir pela linha de comando; olhe direto na lista de plugins na Web UI: abra Settings → Plugins, pesquise por mcp. A imagem abaixo é o meu resultado — depois de digitar mcp na caixa de busca, a lista de plugins está vazia ("nenhum plugin correspondente"), o que significa que não está instalado:

Se você não encontrar na lista, volte para a linha de comando e instale como dependência do profile web:

dsh plugin --profile web add @deepseek-ai/dsh-mcp-client

Observação: este comando apenas empacota-o como dependência do profile (dsh plugin list --profile web mostra a dependência), ele não inicia sozinho — para o plugin ser realmente carregado, é preciso inseri-lo no cordis.patch.yml no passo 3 e configurar os servidores. Existe uma armadilha de teste real: se você inserir apenas o plugin sem a configuração do servidor, o dsh na inicialização vai reportar diretamente Cannot read properties of undefined (reading 'serverName') porque serverName é um campo obrigatório.

Depois de configurar e reabrir o dsh, volte em Settings → Plugins e você verá mcp-client, status "enabled" (a imagem abaixo é depois da instalação, com a caixa de busca ainda mostrando mcp, lista de plugins com 1 item, status enabled):

Passo 2: obtenha uma API Key do Firecrawl

Firecrawl exige autenticação. Faça login no site do Firecrawl, registre-se e crie uma API Key — o uso oficial é enviá-la como token Bearer para https://mcp.firecrawl.dev/v2/mcp. O plano gratuito tem 1000 credits por mês.

A imagem abaixo é a página onde eu criei: à esquerda você vê os créditos restantes, no centro a chave padrão listada (prefixo fc-, meio censurado), no canto superior direito tem + Create:

Depois de obter a chave, primeiro defina-a como variável de ambiente do sistema (a configuração do passo 3 vai referenciá-la). Vou deixar claro uma coisa: variáveis de ambiente não são escritas em arquivo de texto; elas são uma "lista" mantida uniformemente na interface do Windows; a tela de configurações adiciona uma entrada a essa lista. No Windows, use a interface gráfica; sem comandos:

1. Pressione a tecla Win, digite "environment variables", abra Edit the system environment variables
2. Clique no botão Environment Variables no canto inferior direito

3. Na seção User variables clique em New: nome da variável preencha FIRECRAWL_API_KEY, valor da variável preencha fc-your-full-key

4. Clique em OK até fechar todas as janelas

Observação: depois de definir, abra um novo terminal para iniciar o dsh — janelas já abertas não leem automaticamente variáveis de ambiente recém-definidas.

Passo 3: declare o Firecrawl na configuração do Profile

A configuração do servidor MCP é escrita no arquivo patch do profile web (o cordis.patch.yml do CH 08):

• Windows: C:\Users\<seu-usuário>\.dsh\profiles\web\cordis.patch.yml
• macOS / Linux: ~/.dsh/profiles/web/cordis.patch.yml

Adicione um servidor à lista insert, usando o método streamable-http recomendado oficialmente (conecta a um endpoint remoto):

Em cada entrada insert, serverName é obrigatório (o erro de inicialização do passo 1 foi causado por estar vazio) — é o namespace para nomes de ferramentas, e decide como fica mcp__<aqui>__tool.

O endpoint remoto oficial do Firecrawl é https://mcp.firecrawl.dev/v2/mcp, autenticado com um token Bearer:

- insert:
    - id: mcp-firecrawl
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: firecrawl
        transport: streamable-http
        url: https://mcp.firecrawl.dev/v2/mcp
        headers:
          Authorization: !!js '`Bearer ${process.env.FIRECRAWL_API_KEY}`'

A chave é referenciada por meio da variável de ambiente (process.env.FIRECRAWL_API_KEY), e não diretamente hardcoded no arquivo (veja no passo 2 como definir a variável de ambiente) — uma vez commitado no Git, poderia vazar. Para conectar outros servidores MCP depois, basta adicionar outra entrada insert nesse formato.

Algumas descrições de campos comuns:

Campo	Significado
serverName	O namespace do nome da ferramenta (mcp__<aqui>__tool), 1–32 caracteres alfanuméricos com underscore, único dentro de um escopo
transport	stdio (programa local) ou streamable-http (serviço remoto)
command / args / env	O executável, argumentos, variáveis de ambiente extras para stdio
url / headers	Endereço do endpoint HTTP e headers extras da requisição (o token de autenticação vai aqui)
toolCallTimeoutMs	Timeout por chamada de ferramenta (padrão 60 segundos)
reconnect	Política de reconexão automática em desconexão (padrão ativado, backoff inicial 500ms dobrando, teto 30s, desiste após 10 falhas consecutivas)

Após editar e salvar, o arquivo fica assim — a seção insert recém-adicionada está destacada:

Passo 4: reinicie, deixe o modelo chamar

Reabra o dsh e espere terminar de iniciar. As ferramentas do Firecrawl não têm uma "página de lista de ferramentas" dedicada para você olhar; a forma mais direta de confirmar é deixar o modelo usar uma vez:

1. Na sessão, envie: Use o Firecrawl para fazer scraping do conteúdo principal de deepseek.com
2. Observe a resposta do modelo e a Trajectory: se a conexão for bem-sucedida, o modelo chamará mcp__firecrawl__firecrawl_scrape, uma linha TOOL aparece na Trajectory, e o painel lateral mostra o parâmetro url e o resultado markdown raspado

3. Se a ferramenta não aparecer, o modelo dirá explicitamente "eu não tenho essa ferramenta de scraping aqui", ou simplesmente recorrerá à pesquisa web integrada — ambos indicam que o servidor não está conectado; volte à seção anterior para diagnosticar

Quer poupar trabalho? Instale dois plugins da comunidade

A build oficial não tem uma página de "lista de ferramentas" nem uma entrada de "navegar plugins"; a comunidade preencheu esses dois pontos, ambos precisando de apenas um comando:

① Marketplace de plugins dsh-market (987 stars): depois de instalado, em Settings aparece um novo "Plugin Market" onde você pode navegar por categoria, pesquisar e instalar plugins da comunidade com um clique. A maioria dos plugins instalados pelo marketplace passa a valer apenas com atualizar a página, sem precisar reiniciar o dsh:

dsh plugin --profile web add dshmarket

② Painel de visualização MCP DSH Skill & MCP Panel (108 stars): depois de instalado, em Settings aparece um novo "MCP Management"; o status e a contagem de ferramentas de cada servidor ficam diretamente visíveis, adicionar/remover/editar, iniciar/parar podem ser feitos na UI sem editar cordis.patch.yml. Sem precisar digitar comandos — pesquise dsh-skill-mcp-panel diretamente no marketplace ①, instale com um clique, passa a valer após atualizar a página (alguns plugins a nível de host dirão "restart required", basta seguir a instrução):

Esses dois plugins são exatamente a nota de rodapé daquela frase no início deste capítulo — tudo é um plugin: capacidades oficiais de UI que não existem, plugins da comunidade preenchem, e uma vez instalados passam a fazer parte do dsh.

Há muito mais sobre instalação e gerenciamento de plugins — instalação via linha de comando, auto-montagem de bundle, global vs Profile. Este capítulo apenas abre uma janela sobre isso no cenário do MCP; mais adiante, um capítulo inteiro vai abordar sistematicamente a instalação de plugins, depois partirá para o desenvolvimento de plugins, e conectará tudo até a prática em cenários.

Perguntas comuns

Problema	Como lidar
Conectado mas não vê a ferramenta?	Primeiro verifique nos logs se há erros de conexão/descoberta; confirme que o servidor em si está acessível (use um navegador ou curl para testar o endpoint diretamente); confirme que serverName não colide com outro servidor; para servidores que exigem auth, confira se a chave está sendo passada corretamente (401/403 geralmente é isso)
Onde colocar as chaves de serviços como Firecrawl?	Passe via headers na configuração (método HTTP), defina a chave como variável de ambiente antes de iniciar (passo 2), não coloque hardcoded no cordis.patch.yml — uma vez commitado no Git, pode vazar
E se o servidor cair?	O plugin reconecta automaticamente (backoff inicial 500ms dobrando), as ferramentas continuam listadas durante a reconexão, mas as chamadas falham; após 10 falhas consecutivas, as ferramentas são removidas até reload da configuração ou reinício. Editar a configuração recarrega as conexões do servidor in-loco, nomes inalterados permanecem inalterados
Vai consumir muitos tokens?	A descrição e o schema de entrada das ferramentas de cada servidor entram em cada requisição. Conecte apenas o que você realmente usa; não acumule um monte

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Explicar o que o MCP faz, e como o dsh se conecta a ele (um plugin dsh-mcp-client)
• [ ] Saber que a nomenclatura de ferramentas tem dois níveis: um servidor MCP tem várias ferramentas, após conectadas aparecem como mcp__server-name__tool-name
• [ ] Saber como as chaves de servidores MCP que exigem auth (como Firecrawl) são passadas, e por que não são hardcoded no arquivo de configuração
• [ ] Ser capaz de declarar um servidor MCP no cordis.patch.yml (pelo menos um de stdio ou streamable-http)
• [ ] Ter o modelo realmente chamando uma ferramenta MCP, e ver a chamada com prefixo mcp__ na Trajectory
• [ ] Quando o servidor falha ao conectar ou cai, saber onde procurar erros e como diagnosticar
• [ ] Saber que, por conveniência, você pode instalar dois plugins da comunidade: dsh-market (Plugin Market) e DSH Skill & MCP Panel (visualização MCP)