Servidores MCP no OpenClaw: Conectando Ferramentas Externas ao Seu Agente

Um agente OpenClaw pronto pra usar lê arquivos, roda comandos shell e busca na web. Isso cobre uns 30% do que você vai querer que ele faça de verdade. Os outros 70% são coisas tipo "me manda Telegram quando o deploy terminar", ou "consulta o Postgres de produção pra ver os signups de ontem", ou "posta um draft no Slack pra revisão".

Esse buraco é o que o MCP — Model Context Protocol — vem preencher. É o padrão que a Anthropic lançou pra agentes conversarem com ferramentas externas sem você escrever integração custom toda vez.

Tenho oito servidores MCP plugados no meu agente agora. Alguns instalei em cinco minutos a partir de um registry. Dois escrevi do zero numa tarde. O que aprendi fazendo isso está abaixo.

O Que um Servidor MCP de Fato É

Tirando o jargão, um servidor MCP é só um processo que expõe uma lista de ferramentas pro agente via protocolo JSON-RPC. O servidor diz "consigo fazer essas cinco coisas, esses são os parâmetros que cada uma aceita". O agente decide quando chamar.

O transporte normalmente é stdio (servidor roda como subprocess) ou HTTP. Pra coisa local, stdio resolve e é o que a maioria dos servidores já vem.

Uma config mínima em ~/.claude/mcp.json fica assim:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/myapp"]
    }
  }
}

Pronto. Reinicia o agente e mcp__postgres__query aparece como ferramenta chamável. O agente já consegue fazer perguntas pro banco em linguagem natural e você não escreveu uma linha de cola.

Servidores Que Valem a Pena

Depois de rodar vários em produção, esses são os que eu instalaria já no primeiro dia:

Postgres / SQLite — Deixa o agente consultar e inspecionar bancos sem você escrever wrapper de CLI. O servidor oficial é read-only por padrão, que é a escolha certa. Se quiser writes, sobe um segundo servidor com connection string que permita escrita.

Filesystem — Sandbox o agente numa árvore específica de diretórios. Sim, o agente já lê e escreve arquivos via shell, mas a versão MCP é mais rápida e a fronteira do sandbox é forçada no nível do servidor, não só na esperança de que o agente obedeça as instruções.

Telegram (ou Slack) — Esse é o que transforma um script em um colega de trabalho. Quando seu agente consegue te avisar no Telegram quando algo interessante acontece, você para de ficar olhando log. Ele te conta. O plugin oficial de Telegram MCP cuida do bot token, roteamento de mensagens e até anexos.

GitHub — Lê PRs, posta comentários, cria issues. Vale a pena instalar se você quer o agente participando de fluxos de code review.

Browser automation (Playwright) — Deixa o agente abrir URLs, clicar coisa, preencher formulário. Mais lento que requests HTTP, mas necessário pra sites que exigem JavaScript ou têm proteção anti-bot.

Episodic memory — Busca conversas passadas semanticamente. Uso isso o tempo todo. Sem isso o agente esquece tudo entre sessões e reconstruir contexto toda vez sai caro.

O padrão em todos: o servidor MCP cuida da parte difícil (auth, parsing, retry) e expõe uma interface limpa de ferramenta. Você não tem que reinventar nada.

Escrevendo Seu Próprio Servidor

Cedo ou tarde você vai querer uma ferramenta que não existe ainda. O SDK da Anthropic deixa isso curto.

Aqui vai um servidor mínimo em TypeScript que expõe uma ferramenta:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-tools", version: "1.0.0" });

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "ping_uptime_check",
    description: "Check if a URL is responding with HTTP 200",
    inputSchema: {
      type: "object",
      properties: { url: { type: "string" } },
      required: ["url"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name === "ping_uptime_check") {
    const r = await fetch(req.params.arguments.url);
    return { content: [{ type: "text", text: `Status ${r.status}` }] };
  }
});

await server.connect(new StdioServerTransport());

Adiciona no mcp.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["/abs/path/to/server.js"]
    }
  }
}

Pronto. Levei talvez vinte minutos lendo os docs.

Os Tropeços

Algumas coisas me morderam que a documentação não fala logo de cara.

Colisão de nome de ferramenta. Se dois servidores MCP expõem ferramenta com mesmo nome, o agente fica confuso ou um vence silenciosamente. Coloca namespace nos nomes das suas ferramentas (mycompany_uptime_ping, não ping).

Stdio significa que buffer importa. Se seu servidor próprio printa log de debug em stdout, você corrompe o protocolo JSON-RPC e nada funciona. Manda todo log pra stderr. Sempre.

Restart quando muda config. O agente lê mcp.json no startup. Se você editar o arquivo no meio da sessão, nada acontece até reiniciar. Isso me custou vinte minutos da primeira vez.

Tokens de auth em texto plano. Configs de MCP ficam no seu home em JSON cru. Se você está colocando credenciais de produção lá, encripta o arquivo em repouso ou usa expansão de variável de ambiente ("env": {"DB_PASSWORD": "${MY_PASSWORD}"}) e carrega a variável de um vault.

Ferramentas de longa duração dão timeout. O timeout padrão de chamada é 60 segundos. Se sua ferramenta roda um render de vídeo de 10 minutos, o agente vai achar que falhou e tentar de novo. Ou aumenta o timeout na config do servidor, ou faz a ferramenta retornar um job ID na hora e expõe uma ferramenta separada check_status.

Quando MCP Não É a Resposta Certa

MCP é ótimo pra ferramentas que o agente decide chamar. É a escolha errada pra coisas que o agente deveria fazer todo turno — essas vão no system prompt ou como skills auto-carregadas. Também é exagero pra script de uma vez só. Se você só quer o agente rodar um arquivo Python uma vez, Bash("python script.py") é mais rápido que envelopar em MCP.

Regra prática: se você quer essa capacidade disponível em várias sessões e contextos do agente, vira servidor MCP. Se é específica de uma tarefa, comando shell ou skill é mais leve.

O Que Isso Destrava

Quando seu agente tem cinco ou seis servidores MCP plugados, a conversa muda. Você para de dizer "escreve um script que faz X" e começa a dizer "faz X". O agente decide qual ferramenta usar, chama, lida com erro, tenta de novo se preciso, e te conta o resultado.

Essa virada é o que as pessoas querem dizer quando falam em agentes em vez de chatbots. O modelo não ficou mais inteligente — só ganhou mãos maiores.