MCP e LLM local: conectar servidores MCP a Ollama

#O que é MCP e por que ele muda os agentes locais

MCP (Model Context Protocol) é um protocolo aberto publicado pela Anthropic no final de 2024. Seu objetivo: oferecer uma interface única entre um modelo de linguagem e as ferramentas que ele pode usar. Em vez de recodificar uma integração personalizada para cada fonte de dados, um “servidor MCP” expõe ferramentas (tools), recursos (resources) e prompts segundo um formato padrão. Qualquer cliente compatível — Claude Desktop, um IDE ou seu próprio bridge — pode então se conectar a ele.

Na prática, um servidor MCP “filesystem” expõe ferramentas como read_file, write_file ou list_directory. Um servidor “sqlite” expõe query ou list_tables. O LLM nunca fala diretamente com o disco: ele emite uma solicitação de chamada de ferramenta, o cliente a executa via o servidor MCP e depois retorna o resultado para o modelo. Essa separação cliente/servidor é o que torna o protocolo reutilizável.

Para os agentes locais, o desafio é duplo: reutilizar o ecossistema crescente de servidores MCP (já existem dezenas), mantendo a inferência 100% na sua máquina graças ao Ollama. Você obtém um agente que lê seus arquivos e consulta seus bancos de dados sem que um único byte saia da sua rede.

#Por que conectar o MCP ao Ollama

A maioria das demonstrações MCP usa um modelo na nuvem (Claude, GPT). Usar MCP com Ollama localmente muda o cenário em três pontos: a confidencialidade (seus arquivos e consultas SQL não saem), o custo (nenhum token é cobrado, independentemente do volume de chamadas de ferramentas) e o controle (você escolhe o modelo, a quantização e os servidores autorizados).

Privacidade

Um servidor MCP filesystem dá ao modelo acesso às suas pastas. Localmente, esse conteúdo nunca passa por terceiros.

Custo zero

Os agentes multiplicam os ciclos de chamadas a ferramentas e recebimento de resultados. Na nuvem, cada rodada custa tokens; com o Ollama, isso é gratuito.

Offline

Depois que o modelo for baixado e os servidores MCP forem instalados, tudo funciona sem conexão com a internet (exceto, é claro, os servidores web).

Soberania

Você decide quais ferramentas ficam expostas e pode auditar cada chamada antes de executá-la.

#Pré-requisitos

Ollama instalado

O daemon escuta por padrão em http://localhost:11434. Verifique com « ollama --version ».

Um modelo capaz de usar ferramentas

Use pelo menos um Granite 4.2 8B, idealmente um Qwen 3.5 9B para ter confiabilidade (veja a seção seguinte).

Python 3.10+

O SDK MCP oficial e o cliente Ollama são escritos em Python.

Node.js (opcional)

Muitos servidores MCP de referência são iniciados via npx (@modelcontextprotocol/server-*).

# Vérifier Ollama
ollama --version
curl http://localhost:11434/api/tags

# Tirer un modèle capable de tool-use
ollama pull qwen3.5:9b

# Environnement Python
python -m venv .venv
source .venv/bin/activate
pip install mcp ollama

#Quais modelos locais lidam corretamente com tool use

Nem todos os modelos têm o mesmo desempenho em chamadas de função. Um modelo que “conhece” o formato das ferramentas, mas escolhe mal seus argumentos, tornará o agente inutilizável. Na prática, a geração de 2026 (Qwen 3.5, Granite 4.2) torna o uso de ferramentas confiável a partir de 8-9B, enquanto em 2024 era necessário buscar modelos de 14B. Aqui estão as referências que você pode testar com o Ollama e seu consumo de VRAM em Q4_K_M.

Qwen 3.5 4B / 9B

Excelente suporte ao uso de ferramentas. O 9B (≈6,6 GB de VRAM em Q4, 256k de contexto, visão) é o melhor equilíbrio entre confiabilidade e hardware para um agente local.

Granite 4.2 8B

Uso nativo de ferramentas sólido e muito econômico em tokens (≈5,3 GB em Q4, 128k de contexto). Excelente ponto de entrada com 6 a 8 GB de VRAM.

Mistral Small 24B

Function calling sólido e bom nível em francês (≈14 GB em Q4). Lida bem com esquemas de ferramentas um pouco complexos.

Qwen 3.6 35B-A3B

MoE muito confiável em cadeias de chamadas (≈23 GB em Q4, apenas 3B ativos, portanto rápido). Reserve-o para GPUs de 24 GB do tipo RTX 4090.

Modelos 2-3B

Qwen 3.5 2B ou Granite 4.2 3B cabem em ≈2 GB, mas o desempenho no uso de ferramentas cai rapidamente assim que há várias ferramentas. Evitar para um agente de verdade.

#A bridge MCP-Ollama em Python, passo a passo

Ollama não é um cliente MCP nativo. O papel do bridge é atuar como intermediário: iniciar um servidor MCP, converter suas ferramentas para o formato esperado pela API Ollama, executar o ciclo de chamadas de ferramentas e depois devolver os resultados ao modelo. Usamos o SDK MCP oficial (pacote mcp) e o cliente ollama.

1. 01
   1. Iniciar um servidor MCP

   Iniciamos um servidor MCP como subprocesso via stdio. Aqui, o servidor oficial de filesystem, limitado a uma pasta de trabalho passada como argumento.
2. 02
   2. Liste e converta as ferramentas

   session.list_tools() retorna as ferramentas MCP. Nós as transformamos no formato « tools » esperado por /api/chat do Ollama (name, description, inputSchema → parameters).
3. 03
   3. Loop de chamadas de ferramentas

   Enviamos a mensagem do usuário mais a lista de ferramentas. Se o modelo responder com um tool_call, executamos essa chamada no lado do MCP, reintroduzimos o resultado e repetimos o ciclo até obter uma resposta final.
4. 04
   4. Retornar a resposta

   Quando o modelo não solicita mais nenhuma ferramenta, sua última resposta de texto é o resultado final apresentado ao usuário.

import asyncio
import ollama
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

MODEL = "qwen3.5:9b"

# Serveur MCP filesystem limité au dossier ./workspace
server = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "./workspace"],
)

def to_ollama_tools(mcp_tools):
    return [{
        "type": "function",
        "function": {
            "name": t.name,
            "description": t.description,
            "parameters": t.inputSchema,
        },
    } for t in mcp_tools]

async def run(prompt: str):
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = (await session.list_tools()).tools
            ollama_tools = to_ollama_tools(tools)
            messages = [{"role": "user", "content": prompt}]

            while True:
                resp = ollama.chat(
                    model=MODEL,
                    messages=messages,
                    tools=ollama_tools,
                )
                msg = resp["message"]
                messages.append(msg)

                if not msg.get("tool_calls"):
                    return msg["content"]

                for call in msg["tool_calls"]:
                    fn = call["function"]
                    result = await session.call_tool(
                        fn["name"], fn.get("arguments", {}),
                    )
                    text = "".join(c.text for c in result.content
                                    if getattr(c, "text", None))
                    messages.append({
                        "role": "tool",
                        "content": text,
                    })

if __name__ == "__main__":
    print(asyncio.run(run("Liste les fichiers du dossier et résume leur contenu.")))

#Exemplos de servidores MCP úteis para auto-hospedagem

O valor do MCP vem do catálogo de servidores prontos para uso. A seguir, estão os que trazem mais valor para um agente local, todos podendo ser iniciados via npx ou pip.

filesystem

Leitura / gravação de arquivos em uma pasta raiz obrigatória. O mais útil para um agente que trabalha nos seus documentos.

sqlite / postgres

Consultar uma base local em linguagem natural. Coloque a conexão no modo somente leitura para evitar qualquer modificação.

fetch

Obter e converter uma página da web em texto. O único que pressupõe uma conexão com a internet.

git

Explorar um repositório: log, diff, status. Útil para um agente de revisão ou de documentação de código.

memory

Um armazenamento persistente de chave-valor que fornece memória de longo prazo ao agente entre as sessões.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
    },
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data/app.db"]
    }
  }
}

#Os limites reais dos modelos pequenos

Uma ponte funcional não garante um bom agente. O elo mais fraco continua sendo o modelo. Nos modelos mais leves (2-4B), vários problemas surgem sistematicamente assim que a tarefa se complica.

Escolha de ferramenta inadequada

O modelo chama read_file quando deveria chamar list_directory, ou inventa o nome de uma ferramenta. Comum abaixo de 7B.

Argumentos malformados

Caminhos relativos incorretos, JSON inválido nos argumentos. Um bom prompt de sistema e descrições claras das ferramentas atenuam o problema.

Encadeamentos curtos

Os modelos pequenos têm dificuldade além de 2-3 chamadas consecutivas e perdem o fio do objetivo.

Ignorar o resultado

O modelo chama uma ferramenta e depois responde sem levar em conta o que recebeu. Sintoma clássico de um modelo leve demais.

#Solução de problemas

O modelo não faz nenhuma tool_call

Verifique se ele suporta o uso de ferramentas (Qwen 3.5, Granite 4.2) e se o parâmetro “tools” está sendo passado corretamente para /api/chat. Um modelo não compatível ignora as ferramentas.

« connection refused » na porta 11434

O daemon Ollama não está em execução. Inicie-o (« ollama serve ») e teste novamente « curl http://localhost:11434/api/tags ».

O servidor MCP não inicia

Teste o comando npx / uvx isoladamente em um terminal. Se um servidor Node estiver faltando, instale o pacote correspondente com « npm i -g ».

Loop infinito de ferramentas

Adicione um limite de iterações no loop e registre cada tool_call para identificar o modelo que repete a mesma chamada.

#Para se aprofundar

O MCP se apoia nos componentes básicos do ecossistema local. Estes guias relacionados do site complementam este guia:

Criar um agente de IA local com LangChain e Ollama

A abordagem clássica de agentes via LangChain, complementar ao MCP para orquestrar ferramentas.

Integrar Ollama por meio da API REST em Python

Entender o endpoint compatível com OpenAI e o function calling que fundamentam a bridge.

Escolher sua quantização (Q4, Q5, Q8, FP16)

Fazer um Qwen 3.5 9B com uso de ferramentas caber na memória da sua GPU sem sacrificar a confiabilidade.