Configurar MCP no Ollama 2026: conecte modelos locais a arquivos, bancos de dados e APIs

Fatos rápidos

• Protocolo: JSON-RPC 2.0 sobre stdio (subprocesso local) ou Streamable HTTP (remoto). O antigo transporte HTTP+SSE está obsoleto. Os agentes locais usam quase exclusivamente stdio. A revisão atual da especificação é 2026-07-28.
• Origem: criado pela Anthropic como especificação aberta (modelcontextprotocol.io). Apenas alguns servidores de referência ainda são mantidos em modelcontextprotocol/servers (filesystem, git, fetch, memory e outros); SQLite, PostgreSQL, Puppeteer e GitHub foram movidos para servers-archived. Hoje os fornecedores publicam seus próprios servidores.
• Clientes locais: Goose (open source, repositório aaif-goose/goose), Cline (extensão do VS Code), Continue.dev (VS Code/JetBrains), LM Studio (aplicativo de desktop), mais várias ferramentas CLI.
• Modelos Ollama compatíveis: qualquer modelo com treinamento nativo de tool calling, por exemplo Gemma 4 31B, GLM-4.7 Flash, Qwen3.6 27B, Qwen3 32B, Qwen3-Coder 30B, Llama 3.3 70B.
• Transporte padrão dos servidores: stdio para processos locais; Streamable HTTP apenas quando você precisa compartilhar um servidor entre máquinas ou agentes.
• A configuração vive no cliente: o Goose lê um bloco extensions em ~/.config/goose/config.yaml (ou goose configure); Cline e Continue.dev têm suas próprias configurações de MCP. Os campos têm a mesma ideia em todos: nome do servidor, comando, args, variáveis de ambiente.
• Claude Desktop não é necessário. O protocolo é aberto e independente do Claude Desktop; os servidores usados aqui são open source (confira a licença de cada um) e funcionam com qualquer cliente compatível.

O que o MCP realmente desbloqueia para um modelo local

• "Encontre todos os TODOs neste repositório, agrupe-os por arquivo e escreva um resumo em Markdown em notes/todos.md." — o servidor filesystem lê, o modelo agrupa, o mesmo servidor escreve. Uma única ida e volta de ponta a ponta.
• "Mostre-me os 10 melhores clientes por receita neste trimestre e faça um gráfico." — o servidor postgres executa o SQL (role de somente leitura), o modelo resume e escreve um CSV via filesystem para sua ferramenta de gráficos.
• "Abra a capa do Hacker News, encontre as três principais histórias de IA, resuma-as e adicione-as à minha lista de leitura." — o servidor playwright controla um navegador, o modelo extrai e resume, filesystem adiciona.
• "Abra um PR draft com o título chore: bump deps contra meu fork e ligue a execução de CI com falha." — o servidor github cria o PR, obtém a execução e escreve o link na descrição.
• "Olhe as últimas 100 linhas de events.db e diga-me quais IDs de usuário são responsáveis pelo novo pico de erros." — um servidor de banco de dados consulta uma cópia dos dados; o modelo raciocina; você lê a resposta no painel de chat.
• Cada um desses é um fluxo de trabalho de frase para ação que antes exigia um modelo na nuvem com ferramentas hospedadas ou um script escrito à mão. O MCP é a camada que permite reutilizar os mesmos servidores entre clientes e o mesmo modelo entre servidores.

Comparativo dos quatro servidores MCP mais usados

Como as peças se encaixam

• Ollama roda como serviço em segundo plano em 127.0.0.1:11434 e serve o modelo via uma API compatível com OpenAI. Não sabe o que é MCP — simplesmente responde às completações de chat e emite tool calls quando o modelo os solicita.
• O cliente MCP (Goose, Cline, Continue.dev, LM Studio) é a ponte. Fala com o Ollama para o modelo e com os servidores MCP para as ferramentas. Quando o modelo emite um tool call, o cliente o roteia para o servidor correto, obtém o resultado e o retorna à conversa.
• Os servidores MCP são subprocessos independentes, um por capacidade. Falam JSON-RPC 2.0 sobre stdio. Cada servidor anuncia uma lista de Tools, Resources e Prompts; o cliente os combina na superfície de ferramentas que é apresentada ao modelo.
• O transporte stdio mantém tudo local. O servidor é iniciado pelo cliente, se comunica via seu stdin/stdout e termina quando o cliente termina. Nada vai pela rede a menos que o servidor em si abra uma conexão (o servidor de navegador o faz; os servidores de filesystem e banco de dados não).
• O modelo vê uma lista plana de ferramentas. Da perspectiva do modelo não há servidores — apenas uma lista de nomes de ferramentas como filesystem.read_file, playwright.browser_navigate, github.create_pull_request. O cliente gerencia o roteamento.

Configuração: Ollama + Goose em 15 minutos

• Passo 1 — instale o Ollama. Baixe em ollama.com/download (macOS/Windows/Linux). Confirme que o serviço está rodando com curl http://127.0.0.1:11434/api/tags.
• Passo 2 — baixe um modelo com tool calling. Escolha entre Gemma 4 31B (gemma4:31b), GLM-4.7 Flash (glm-4.7-flash), Qwen3.6 27B (qwen3.6:27b), Qwen3 32B (qwen3:32b) ou Llama 3.3 70B (llama3.3:70b). 32 GB de memória unificada ou 24 GB de VRAM lidam confortavelmente com 26B–32B em Q4_K_M.
• Passo 3 — instale o Goose. No macOS ou Linux, execute curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash (ou brew install block-goose-cli). No Windows, use o instalador PowerShell da documentação do Goose, ou o WSL. O CLI se instala como goose.
• Passo 4 — configure o Ollama como provedor. Execute goose configure, escolha ollama como provedor, defina o modelo que você baixou e o host como http://127.0.0.1:11434 (em branco também significa localhost:11434). O Goose escreve isso em ~/.config/goose/config.yaml. A janela de contexto padrão do Ollama pode ser pequena (a documentação do Goose menciona 4096 tokens), o que pode fazer o Goose ignorar suas extensões — inicie o Ollama com OLLAMA_CONTEXT_LENGTH=32768 (ou mais).
• Passo 5 — adicione o servidor MCP de filesystem. Execute goose configure, escolha Add Extension e depois Command-line Extension, ou adicione um bloco extensions a ~/.config/goose/config.yaml (exemplo abaixo). Para um teste pontual, goose session --with-extension "npx -y @modelcontextprotocol/server-filesystem /path/to/workspace" o ativa apenas naquela sessão. Inicie goose session e peça que liste os arquivos no seu diretório de teste. O primeiro turno confirma que o servidor está conectado.
• Passo 6 — verifique com uma tarefa real. Teste goose session e peça "Faça uma lista de cada arquivo Markdown em notes/, com título e número de palavras, e escreva o resultado em notes/index.md." Se o agente ler, resumir e escrever de volta, o loop funciona.

# 1. Pull a tool-calling model
ollama pull gemma4:31b

# 2. Install Goose (macOS / Linux)
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 3. Configure Ollama as the provider
goose configure
# Provider: ollama
# Model:    gemma4:31b
# Host:     http://127.0.0.1:11434

# 4. Give Ollama a context window big enough for tool use, then start a session
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # in a separate terminal
goose session

Servidor Filesystem: ler e escrever em um diretório isolado

• Instalação: o servidor de referência é @modelcontextprotocol/server-filesystem, executado via npx -y (sem instalação global; requer Node.js). É um dos servidores de referência que ainda são mantidos. Goose, Cline e Continue.dev o iniciam a partir da configuração.
• Caminhos na allowlist: o servidor aceita um ou mais argumentos de diretório e rejeita operações fora deles. Sempre passe um caminho explícito e estreito — nunca ~ nem /.
• Ferramentas expostas: read_file, read_multiple_files, write_file, edit_file (substituições por linha), list_directory, search_files, move_file, create_directory, directory_tree. O modelo as vê como filesystem.read_file e assim por diante.
• Conveniência de uso: directory_tree retorna uma árvore JSON; ideal para o modelo se orientar antes de ler arquivos específicos. search_files faz uma busca recursiva similar ao grep.
• Superfície de risco: o servidor respeita a allowlist, mas dentro dela tem leitura/escrita completa. Trate a allowlist como a única barreira e escolha um diretório workspace dedicado em vez da sua pasta home.

# ~/.config/goose/config.yaml
extensions:
  filesystem:
    type: stdio
    name: filesystem
    enabled: true
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/agent-workspace"]
    envs: {}
    timeout: 300

Servidores de banco de dados: consultar o Postgres (e o SQLite) com segurança

• Postgres: postgres-mcp (Crystal DBA, licença MIT) é a opção com modo somente leitura (a versão mais recente no PyPI é de maio de 2025, então confira a atividade do repositório antes de depender dele). Execute-o com uvx postgres-mcp --access-mode=restricted (ou pipx install postgres-mcp, ou sua imagem Docker) e passe a URI de conexão na variável de ambiente DATABASE_URI. O modo restrito permite transações somente leitura e um limite de tempo por consulta; o modo irrestrito é só para desenvolvimento.
• Use também um role de somente leitura dedicado. O modo restrito é uma barreira, o role do banco de dados é outra. Crie um role agent_ro com permissões apenas de SELECT e use a string de conexão desse role.
• SQLite: o servidor de referência está arquivado. É o pacote Python mcp-server-sqlite (não é um pacote npm; última versão em abril de 2025), pode até continuar funcionando, mas não recebe correções. Aponte-o apenas para uma cópia do arquivo, nunca para a sua única cópia, ou carregue os dados no Postgres. Leia o código de qualquer servidor SQLite da comunidade antes de entregar um arquivo a ele.
• Consciência do esquema: peça ao agente que "liste as tabelas e descreva as cinco mais usadas" antes de fazer perguntas analíticas — o modelo é muito mais preciso quando inspecionou o esquema do que quando adivinha os nomes das colunas.
• Custo: as consultas vão diretamente ao seu banco de dados. Um SELECT * malformado de uma tabela com 100M de linhas é o mesmo acidente aqui que seria de um humano — mantenha o role em um pool de conexões separado com um statement timeout.

# ~/.config/goose/config.yaml
extensions:
  postgres:
    type: stdio
    name: postgres
    enabled: true
    cmd: uvx
    args: ["postgres-mcp", "--access-mode=restricted"]
    envs:
      DATABASE_URI: "postgresql://agent_ro:${PG_AGENT_PASSWORD}@127.0.0.1:5432/analytics"
    timeout: 300

Servidor de navegador: controlar um navegador com o Playwright MCP

• Qual servidor: use o @playwright/mcp da Microsoft (npx @playwright/mcp@latest). O antigo @modelcontextprotocol/server-puppeteer está marcado como "no longer supported", e não existe nenhum pacote @modelcontextprotocol/server-playwright no npm.
• Ferramentas expostas: browser_navigate, browser_snapshot, browser_click, browser_type, browser_fill_form, browser_evaluate (executar JavaScript), browser_take_screenshot, browser_tabs, browser_wait_for. O modelo lê a página por meio de browser_snapshot (um snapshot de acessibilidade, que o Playwright MCP recomenda em vez de capturas de tela para executar ações) e usa capturas de tela apenas para olhar.
• Latência: sessões de navegador reais levam entre 1 e 5 segundos por ação. Uma navegação de múltiplos passos pode facilmente consumir 30–60 segundos e dezenas de milhares de tokens porque o conteúdo das páginas é grande. Use uma janela de contexto de 32K+.
• Referências de elementos: o modelo clica nos elementos pelas referências do snapshot. Modelos menores escolhem o elemento errado com frequência; um modelo de 27B+ com tool calling lida com os padrões comuns de forma confiável. Mantenha as tarefas delimitadas — "extraia o título e o primeiro parágrafo desta URL" é muito mais confiável do que "navegue pelo site e encontre a página de contato".
• Os casos de uso corretos: pesquisa (abrir a página, resumir, adicionar a notas), testes de regressão (navegar, clicar, captura de tela) e preenchimento de formulários em páginas que você controla. Os casos incorretos: qualquer coisa onde um clique errado na web ao vivo tenha consequências.

# ~/.config/goose/config.yaml
extensions:
  playwright:
    type: stdio
    name: playwright
    enabled: true
    cmd: npx
    args: ["@playwright/mcp@latest"]
    envs: {}
    timeout: 300
# Block obviously dangerous endpoints at the OS firewall level
# rather than relying on the agent to refuse them.

Servidor GitHub: repositórios, issues e PRs a partir de um modelo local

• Instalação: use o github/github-mcp-server oficial do GitHub, executado a partir da sua imagem Docker (ghcr.io/github/github-mcp-server) com um PAT na variável de ambiente GITHUB_PERSONAL_ACCESS_TOKEN. O antigo pacote npm @modelcontextprotocol/server-github está marcado como "no longer supported"; não o use em novas configurações.
• Ferramentas expostas: search_repositories, get_file_contents, create_or_update_file, create_pull_request, list_issues, create_issue, add_issue_comment, merge_pull_request, mais muitas outras. A superfície completa é grande; a maioria das tarefas usa de 5 a 10 ferramentas.
• Limite o escopo do PAT. Use um PAT de granularidade fina limitado a repositórios específicos com as permissões mínimas necessárias (Read para navegar, Write para criar PRs/issues). Não use um PAT clássico com repo para um agente experimental.
• Fluxos de trabalho reais: triagem ("leia os últimos 20 issues abertos, agrupe-os, proponha labels"), rascunhos ("leia o README e abra um PR corrigindo erros de digitação"), relatórios ("quais PRs estão inativos esta semana").
• Superfície de risco: o agente pode criar issues e PRs, comentá-los e (com permissões de escrita) fazer push de commits. Desative as ferramentas de merge a menos que você confie tanto no modelo quanto no fluxo de trabalho — um merge feito por engano em um repositório com PAT de granularidade fina é recuperável, mas só se você notar rápido.

# ~/.config/goose/config.yaml
extensions:
  github:
    type: stdio
    name: github
    enabled: true
    cmd: docker
    args: ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
    envs:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GH_AGENT_PAT}"
    timeout: 300
# Fine-grained PAT scoped to one or two test repos,
# not your personal account-wide classic token.

Um modelo de segurança que não confia no modelo

• Limite o servidor filesystem a um diretório. Nunca ~ nem /. Escolha uma pasta agent-workspace/ e coloque cópias dos arquivos que o agente precisa tocar. Se o agente falhar, o pior caso é uma pasta.
• Execute os servidores de banco de dados em somente leitura por padrão. Um role agent_ro dedicado com permissões apenas de SELECT e um statement timeout de 30 segundos elimina toda uma classe de incidentes.
• Coloque cada ferramenta de escrita ou shell atrás de uma aprovação explícita. Goose, Cline e Continue.dev admitem regras de aprovação por ferramenta. Permita as ferramentas de leitura por padrão; exija aprovação para write_file, edit_file, execute_command, create_pull_request e qualquer ação do navegador que envie formulários.
• Use o log de auditoria. Cada cliente MCP registra os tool calls e os resultados. Após uma sessão longa, revise o log: você vai detectar o modelo tentando coisas que não esperava (às vezes inofensivas, às vezes um motivo para apertar as permissões).
• Limite o acesso de terceiros com tokens de escopo estreito. PATs do GitHub limitados a dois repositórios de teste. Roles de Postgres de somente leitura. Sessões de navegador sem credenciais. O modelo acabará tentando coisas que você não previu; os limites do que ele pode fazer não devem depender de ele acertar.
• Isole o agente para trabalho com dados sensíveis. Desative o acesso à rede no host enquanto o agente está rodando (ou use um network namespace) quando trabalhar com dados privados. O stack local já não envia nada para fora da máquina, mas a defesa em profundidade pega erros em servidores de terceiros.
• Trate a seleção de servidores MCP como qualquer escolha de dependência. Os servidores de referência são bem mantidos; muitos servidores de terceiros não são. Leia o código do servidor antes de instalar um que precise de credenciais.

MCP local vs Claude Desktop: o que muda, o que permanece

Escolher um modelo com tool calling para MCP local

• Gemma 4 31B (gemma4:31b) — o treinamento de tool calling do Google é o melhor da categoria para esse tamanho. Cabe em 16 GB de memória unificada ou 24 GB de VRAM em Q4_K_M. Bom raciocínio geral; um pouco conservador em tool calls encadeados.
• GLM-4.7 Flash (glm-4.7-flash) — o modelo da Zhipu tem confiabilidade de tool calling muito alta e uma janela de contexto de 128K nativa. Um pouco mais pesado que o Gemma 4; cabe confortavelmente em uma GPU de 24 GB.
• Qwen3.6 27B (qwen3.6:27b) — a opção mais nova da família Qwen no Ollama (cerca de 18–19 GB, contexto de 256K, com suporte a tool calling). Qwen3 32B (qwen3:32b) — equilibrado; o 32B denso lida com MCP sem problemas e se sente bem em um loop de agente longo. Qwen3-Coder 30B (qwen3-coder:30b) é a melhor opção se seu trabalho de agente é orientado a código.
• Llama 3.3 70B (llama3.3:70b) — o maior teto, mas o mais pesado. 48 GB+ de memória unificada ou 2× 24 GB de GPUs em Q4_K_M. Use apenas se seu hardware comportar; os modelos menores geralmente bastam.
• Evite para trabalho com MCP: qualquer coisa abaixo de 7B e qualquer modelo de uso geral sem treinamento explícito de tool calling. Eles emitirão chamadas malformadas, o loop vai travar e você vai culpar o harness — mas o harness está bem.
• Para técnicas de prompting estruturado que melhoram a qualidade do tool calling em qualquer modelo, veja chain-of-thought prompting.
• Para os dados comparativos, veja Melhores modelos locais para tool calling em 2026.

MCP vs Function Calling simples: qual é a diferença

• O function calling é a capacidade do lado do LLM: o modelo emite um objeto JSON estruturado descrevendo o nome da ferramenta e os argumentos. As tools da OpenAI, as tools da Anthropic e a API de tool calls do Ollama usam a mesma ideia, com formatos de wire ligeiramente diferentes.
• O MCP fica acima: padroniza como as ferramentas são descritas, descobertas, invocadas e retornadas entre processos. Um modelo com function calling, por si só, não sabe nada sobre o seu filesystem; um servidor MCP disponibiliza as operações de arquivo, o cliente as mapeia para a API de function calling do modelo, e o modelo passa a poder chamá-las.
• O benefício é a interoperabilidade. Escreva o servidor filesystem uma vez; Claude Desktop, Goose, Cline, Continue.dev e LM Studio todos o usam sem mudanças. Troque o modelo de Claude para Gemma 4; o servidor não muda.
• Você pode fazer agentes com function calling puro. Você reimplementará handlers de filesystem, banco de dados e navegador por projeto. Com MCP, essas são dependências prontas para uso.
• Para scripts pontuais, o function calling puro é mais simples. Para qualquer coisa que queira reutilizar entre projetos ou modelos, o MCP é o caminho de menor esforço em poucos dias.

Erros comuns ao configurar MCP local

• Erro 1: usar um modelo pequeno de propósito geral. Modelos abaixo de 7B (e a maioria dos modelos gerais de 7B–13B sem fine-tuning de tool calling) emitem tool calls malformados. Use um modelo de 27B+ ajustado para tool calling e pare de lutar com o harness.
• Erro 2: colocar seu diretório home na allowlist. As allowlists de ~ "apenas para testes" sobrevivem até o uso rotineiro. Crie um agent-workspace dedicado desde o início.
• Erro 3: deixar o servidor de banco de dados em modo leitura/escrita. Uma consulta DELETE redigida por um agente autoconfiante em uma tabela real é exatamente o incidente que isso evita. Faça de agent_ro seu role padrão; crie um role com escrita separado apenas para tarefas que realmente precisem dele, e somente durante essas tarefas.
• Erro 4: aprovar automaticamente cada ferramenta. O botão "aprovar tudo" é conveniente e perigoso. Aprove automaticamente as ferramentas de leitura (read_file, list_directory, query); sempre exija aprovação para as ferramentas de escrita/shell/PR.
• Erro 5: usar um modelo com contexto de 32K para trabalho de navegador de múltiplos passos. O conteúdo da página é grande; um agente que navega três páginas pode esgotar os 32K tokens antes de raciocinar. Use um modelo com contexto de 128K para tarefas intensivas no navegador.
• Erro 6: assumir que o agente tem julgamento. Não tem. O modelo não tem conceito de "este é o banco de dados de produção" ou "este PR vai ser implantado". As permissões são sua única barreira.
• Erro 7: instalar todos os servidores de referência desde o início. Mais ferramentas = prompt de sistema maior = seleção de ferramentas mais lenta e menos confiável. Comece com filesystem. Adicione os demais apenas quando tiver um fluxo de trabalho que os precise.
• Erro 8: instalar servidores de referência arquivados a partir de tutoriais antigos. Os pacotes npm @modelcontextprotocol/server-postgres, -puppeteer e -github estão marcados como "no longer supported" e o servidor SQLite está arquivado. Alguns guias antigos também citam pacotes npm que não existem (server-sqlite, server-playwright). Use os servidores mantidos citados acima.
• Erro 9: colocar a configuração de MCP no Ollama. O Ollama não tem configurações de MCP. Os servidores são configurados no cliente (extensions do Goose, configurações de MCP do Cline ou do Continue.dev).

Fontes

• Especificação do Model Context Protocol — Especificação oficial, esquema JSON-RPC, definições de transporte e ciclo de vida, incluindo o changelog de 2026-07-28.
• Repositório GitHub modelcontextprotocol/servers — Os servidores de referência mantidos (filesystem, git, fetch, memory e outros) e a lista de servidores arquivados.
• github/github-mcp-server — Servidor MCP oficial do GitHub, configuração com Docker e binário.
• microsoft/playwright-mcp — Servidor Playwright MCP e suas ferramentas de navegador.
• crystaldba/postgres-mcp — Servidor MCP para Postgres com modo de acesso restrito (somente leitura).
• Documentação do Goose — Instalação do CLI, configuração do provedor Ollama, sintaxe de configuração de extensões (servidores MCP).
• Biblioteca de modelos Ollama — Modelos locais disponíveis, indicadores de suporte de tool calling e níveis de quantização referenciados neste guia.
• Repositório GitHub do Cline — Implementação do cliente MCP para VS Code, painel de servidores MCP.
• Documentação do Continue.dev — Referência do bloco de configuração mcpServers para o cliente Continue.dev.

Perguntas frequentes

Leituras relacionadas

• Melhores modelos locais para tool calling em 2026 — benchmarks comparativos para os modelos recomendados acima (Gemma 4, GLM-4.7, Qwen3, Llama 3.3).
• Os agentes locais autônomos realmente funcionam — uma verificação da realidade sobre o que um agente MCP local pode e não pode fazer de forma confiável em uma tarefa de longa duração.
• Continue.dev vs Cline vs Aider: o melhor agente de código local em 2026 — contexto de agente adjacente para trabalho orientado a código; Cline e Continue.dev também são clientes MCP.
• Melhores LLMs locais em 2026 — referência de modelos para o panorama mais amplo de pesos abertos.
• Substitua o Zapier com agentes de IA locais — framework de automação de fluxos de trabalho para o mesmo stack MCP.
• Hub de Power Local LLM — biblioteca completa de guias.