MCP (Model Context Protocol)

O MCP permite conectar servidores de ferramentas externas ao GarraIA. Qualquer servidor compatível com MCP — acesso ao sistema de arquivos, GitHub, bancos de dados, busca na web, entre outros — torna-se disponível como ferramentas nativas do agente.

Como funciona

Você configura servidores MCP no arquivo config.yml ou em ~/.garraia/mcp.json
Na inicialização, o GarraIA conecta-se a cada servidor habilitado e descobre suas ferramentas
As ferramentas MCP aparecem junto com as ferramentas nativas usando nomes com namespace: servidor.nome_da_ferramenta
O agente pode chamá-las normalmente durante uma conversa

Tipos de transporte

stdio (padrão) O GarraIA inicia o processo do servidor e comunica-se via stdin/stdout.
HTTP Permite conectar a um servidor MCP remoto via HTTP.

Configuração

Servidores MCP podem ser configurados em dois locais. Ambos são combinados automaticamente na inicialização.

config.yml

Adicione uma seção mcp: em:

~/.garraia/config.yml

Exemplo:

mcp:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@2.0.0", "/tmp"]
    enabled: true

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

mcp.json (compatível com Claude Desktop)

Você também pode usar o arquivo:

~/.garraia/mcp.json

Formato:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@2.0.0", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Se o mesmo servidor estiver definido em ambos os arquivos, a configuração do config.yml terá prioridade.

Campos de configuração (McpServerConfig)

Campo	Tipo	Padrão	Descrição
`command`	string	obrigatório	Executável a ser iniciado
`args`	string[]	`[]`	Argumentos de linha de comando
`env`	mapa	`{}`	Variáveis de ambiente do processo
`transport`	string	`"stdio"`	Tipo de transporte (`stdio` ou `http`)
`url`	string	nenhum	URL para transporte HTTP
`enabled`	boolean	`true`	Define se o servidor será conectado na inicialização
`timeout`	inteiro	`30`	Tempo limite de conexão em segundos

Comandos CLI do MCP

Validar que os servidores sobem (`doctor mcp`)

garraia doctor mcp

O health-check de subida, não de instalação: para cada servidor stdio declarado (no mcp: do config.yml ou no mcp.json) ele spawna o servidor pelo mesmo caminho de boot do gateway — mesmo merge, mesma resolução de vault:, mesma recuperação de cache npx — conta as tools que o handshake devolveu e desliga os filhos antes de sair.

Exit	Significado
`0`	todos os servidores stdio declarados subiram com tools
`2`	algum servidor não subiu (ou `--strict` com versão solta)
`65`	o arquivo de config existe mas não parseia

Servidor com enabled: false é decisão do operador e não reprova; entradas HTTP ficam marcadas como não-verificadas por este check. --json emite o mesmo vocabulário do doctor raiz (ok, exit_code, report).

O garraia doctor (sem área) mostra um resumo CONFIG — quantos servidores declarados e se o filesystem está com a versão fixada — sem spawnar nada.

Listar servidores configurados

garraia mcp list

Mostra todos os servidores MCP configurados, incluindo:

Status (habilitado/desabilitado)
Comando
Argumentos
Timeout

Inspecionar ferramentas

garraia mcp inspect <nome>

Conecta-se ao servidor especificado, descobre todas as ferramentas disponíveis e exibe no formato:

servidor.nome_da_ferramenta

Depois desconecta automaticamente.

Listar recursos

garraia mcp resources <nome>

Mostra todos os recursos disponíveis no servidor:

URI
Tipo MIME
Nome
Descrição

Listar prompts

garraia mcp prompts <nome>

Mostra todos os prompts disponíveis:

Nome
Descrição
Argumentos
Campos obrigatórios

Namespace das ferramentas

Ferramentas MCP usam namespace baseado no nome do servidor para evitar conflitos.

Exemplo:

Servidor:

filesystem

Ferramenta:

read_file

Nome final no GarraIA:

filesystem.read_file

Isso permite que múltiplos servidores tenham ferramentas com o mesmo nome sem conflito.

Exemplos

Servidor de sistema de arquivos

Permite ler e escrever arquivos em um diretório específico:

mcp:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem@2.0.0", "/home/user/documentos"]

Servidor GitHub

Permite interação com repositórios GitHub:

mcp:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

Servidor SQLite

Permite consultar um banco de dados local:

mcp:
  sqlite:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-sqlite", "/caminho/para/banco.db"]

Servidor HTTP

Permite conectar a um servidor MCP remoto:

mcp:
  ferramentas-remotas:
    transport: http
    url: "https://mcp.exemplo.com"
    timeout: 60

Detalhes de implementação

O suporte ao MCP é controlado pela feature mcp no crate garraia-agents (habilitado por padrão)
Utiliza o crate oficial Rust MCP SDK: rmcp
O gerenciador está em:

crates/garraia-agents/src/mcp/manager.rs

A ponte entre MCP e ferramentas internas está em:

crates/garraia-agents/src/mcp/tool_bridge.rs

Classe responsável:

McpTool

Estado atual e melhorias

O transporte HTTP nativo (Streamable HTTP) existe atrás da feature de compilação mcp-http, que está desabilitada por padrão — os binários de release suportam apenas stdio como cliente MCP; transport: http na configuração é ignorado com um warning. Para HTTP, compile da fonte com cargo build --release -p garraia --features mcp-http, ou use uma ponte stdio→HTTP (ver mcp.json.example). As operações de recursos e prompts foram integradas ao MCP, permitindo que ferramentas, recursos e prompts sejam expostos como ferramentas nativas pelo agente. Além disso, o gerenciador tenta reconectar automaticamente aos servidores MCP após falhas, garantindo maior resiliência.

Atualmente não há issues abertas relacionadas a essas funcionalidades. Novas melhorias serão avaliadas conforme o feedback da comunidade.

Como funciona​

Tipos de transporte​

Configuração​

config.yml​

mcp.json (compatível com Claude Desktop)​

Campos de configuração (McpServerConfig)​

Comandos CLI do MCP​

Validar que os servidores sobem (doctor mcp)​

Listar servidores configurados​

Inspecionar ferramentas​

Listar recursos​

Listar prompts​

Namespace das ferramentas​

Exemplos​

Servidor de sistema de arquivos​

Servidor GitHub​

Servidor SQLite​

Servidor HTTP​

Detalhes de implementação​

Estado atual e melhorias​