Servidores MCP

O Model Context Protocol (MCP) é um padrão aberto para conectar ferramentas externas a um agente de IA. O Imaginne é um cliente MCP: você aponta para um ou mais servidores MCP e as ferramentas deles passam a ficar disponíveis para o agente, como se fossem ferramentas nativas.

O Imaginne conecta aos servidores MCP que você configura; cada ferramenta vira mcp__<servidor>__<ferramenta> para o agente.

Onde funciona

O MCP roda localmente no Imaginne, então está disponível no Desktop e no Terminal (TUI) — e no processo local que a extensão do VS Code inicia. Não está disponível no chat no navegador (lá o agente roda no servidor).

Configuração por arquivo, sem UI

Hoje não há tela nem comando para gerenciar servidores MCP — você edita um arquivo JSON e as ferramentas passam a aparecer para o agente na próxima sessão. Também não há servidores MCP embutidos: você aponta para um servidor externo.

Configuração

Há dois escopos, ambos no formato .mcp.json com a chave mcpServers:

Escopo	Caminho	Confiança padrão
Usuário	~/.imaginne/mcp.json	confiável (trusted: true)
Projeto	<workspace>/.mcp.json	não confiável (pede aprovação)

Se um servidor com o mesmo nome existir nos dois, o do projeto prevalece.

Exemplo

~/.imaginne/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/voce/projetos"],
      "trusted": true
    },
    "minha-api": {
      "type": "http",
      "url": "https://api.exemplo.com/mcp",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

Campos

Campo	Tipo	Padrão	Descrição
type	string	stdio	Transporte: stdio (processo local) ou http.
command / args / env	string / lista / objeto	—	Para stdio: o processo a iniciar e seu ambiente.
url / headers	string / objeto	—	Para http: o endpoint e cabeçalhos (ex.: Authorization).
enabled	bool	true	Desative sem remover a entrada.
trusted	bool	usuário=true, projeto=false	Servidor confiável pula aprovação em ferramentas só-leitura.
timeout	duração	5m	Tempo máximo por chamada (ex.: 30s, 2m).

Variáveis de ambiente são expandidas em command/args/env/url/headers com $VAR ou ${VAR} — use-as para não escrever segredos no arquivo. Os valores expandidos nunca são registrados em log.

Transportes suportados

Apenas stdio (processo local que fala JSON-RPC) e http. Não há WebSocket, OAuth nem um transporte SSE dedicado.

Como as ferramentas aparecem

Ao conectar, o Imaginne descobre as ferramentas do servidor e as registra no mesmo conjunto que o agente já usa, com nome mcp__<servidor>__<ferramenta> (ex.: mcp__filesystem__read_file). O modelo as chama exatamente como uma ferramenta nativa.

Aprovação e segurança

• Servidor não confiável (padrão dos servidores de projeto): toda chamada de ferramenta pede aprovação.
• Servidor confiável: chamadas só-leitura / não destrutivas rodam sem prompt; ações destrutivas ainda pedem confirmação (com base nas anotações readOnlyHint/destructiveHint do MCP).
• As aprovações aparecem na interface (cartão de permissão no Desktop, prompt na TUI), conforme a sua autonomia.

Confie só no que você conhece

Um servidor MCP pode ler e agir conforme as ferramentas que expõe. Só adicione servidores em que você confia. O .mcp.json de um projeto começa como não confiável de propósito — revise antes de marcar trusted: true.

Passo a passo (exemplo)

1. Instale/escolha um servidor MCP (ex.: um servidor de sistema de arquivos via npx @modelcontextprotocol/server-filesystem).
2. Crie ~/.imaginne/mcp.json com a entrada do servidor (veja o exemplo acima).
3. Reinicie a sessão (feche e reabra o Desktop, ou reinicie a TUI).
4. Peça algo ao agente que use a ferramenta — ele vai acioná-la e, se o servidor não for confiável, pedir aprovação.

Veja também

🧰Skills

A forma governada de dar capacidades ao agente.

Abrir →🚧Regras do workspace

Limite o que o agente (e as ferramentas) podem tocar.

Abrir →🎚️Autonomia

Quanto o agente pergunta antes de agir.

Abrir →