MCP, REST e o Agente integrado

O Eidograph oferece três caminhos para agentes, todos chegando à mesma superfície de ferramentas:

Caminho	Melhor para	Disponível em
Agente integrado	Mudanças em linguagem natural no projeto atual	Aplicativos Windows e Android
MCP Streamable HTTP	Plataformas de agente que suportam MCP remoto via HTTP	Aplicativo Windows
API REST JSON	Scripts, fluxos de trabalho e agentes personalizados	Aplicativo Windows

Antes que uma ferramenta altere um script, o Eidograph compila a alteração candidata. Uma edição com erros de compilação ou um aviso de comando ignorado é rejeitada, e o script atual permanece inalterado. Edições bem-sucedidas são persistidas, redesenhadas e entram imediatamente no histórico normal de desfazer.

Ativar o servidor nativo

1. No aplicativo instalado, abra Configurações › Servidor MCP / REST.
2. Ative o servidor e confirme que seu status está em execução. A porta padrão é 14159.
3. Ative apenas as ferramentas que o cliente precisa.
4. Em Figuras, verifique o indicador de exposição ao lado de cada figura. Um indicador preenchido significa que clientes externos podem acessá-la.
5. Mantenha a vinculação padrão a loopback, a menos que você esteja em uma rede confiável.

Endpoints padrão:

MCP   http://127.0.0.1:14159/mcp
REST  http://127.0.0.1:14159/api/v1

DANGER

O modo de rede local se vincula a 0.0.0.0 e não tem retransmissão pela internet. Clientes nativos nessa rede podem invocar as ferramentas que você ativou, então ative um token de acesso antes de ligar o modo de rede local, use-o apenas em uma rede confiável e desative-o depois.

Exigir um token de acesso

O servidor não exige autenticação por padrão, o que é seguro o bastante enquanto ele fica em loopback: só programas já em execução neste PC conseguem alcançá-lo. Ative Configurações › Servidor MCP / REST › Exigir um token de acesso — sempre antes de habilitar o modo de rede local — e o Eidograph gera um segredo que toda requisição precisa levar:

Authorization: Bearer <token>

Requisições sem esse cabeçalho recebem 401. As configurações mostram o token com um botão de cópia, Substituir o token o rotaciona e desligar a chave o apaga. Os dois têm efeito imediato, então atualize todos os clientes que você configurou.

Encontrar o servidor a partir de outro programa

A porta é uma configuração, então nada fora do aplicativo pode presumi-la. Enquanto o servidor escuta, o Eidograph publica um arquivo de descoberta e o remove quando o servidor para ou o aplicativo é fechado:

Plataforma	Caminho
Windows	%LOCALAPPDATA%\eidograph.metaphor.projects\server.json
macOS	~/Library/Application Support/eidograph.metaphor.projects/server.json
Linux	$XDG_DATA_HOME/eidograph.metaphor.projects/server.json

{
  "version": "0.2.19",
  "pid": 24680,
  "updatedAt": 1757000000000,
  "bindAddress": "127.0.0.1",
  "port": 14159,
  "mcp": "http://127.0.0.1:14159/mcp",
  "api": "http://127.0.0.1:14159/api/v1",
  "token": "3f9c…",
  "lanAddresses": []
}

Leia mcp ou api e envie token como token bearer; ele é null quando nenhum é exigido. As URLs publicadas permanecem em loopback mesmo no modo de rede local, porque quem lê este arquivo está na mesma máquina. Configurações › Servidor MCP / REST mostra e copia o caminho exato. Trate a ausência do arquivo como "o servidor não está em execução", em vez de recorrer a uma porta adivinhada.

Claude Desktop

O Claude Desktop instala servidores MCP como processos stdio locais, então não aceita colar uma URL HTTP. Instale a extensão eidograph-mcpb para fazer a ponte — ela não precisa de configuração, encontra sozinha a porta e o token de acesso, e relê os dois a cada requisição. Veja Claude Desktop para a instalação passo a passo com capturas de tela, e como apontá-la para um Eidograph rodando em outro dispositivo.

Conectar uma plataforma MCP

Para um cliente que suporta Streamable HTTP — incluindo a configuração para Trae / WorkBuddy copiada pelo aplicativo — adicione este servidor:

{
  "mcpServers": {
    "Eidograph": {
      "url": "http://127.0.0.1:14159/mcp",
      "transport": "streamable-http",
      "disabled": false
    }
  }
}

As plataformas diferem no local do arquivo de configuração e no esquema externo, mas os valores essenciais são o nome do servidor, a URL e o transporte Streamable HTTP. Se uma plataforma suporta apenas um processo MCP stdio local, não coloque essa URL no campo command dela; use um conector HTTP ou uma ponte suportada por essa plataforma.

Depois de conectar, deixe o cliente descobrir as ferramentas e, em seguida, leia o script atual ou o registro de comandos. Uma sequência confiável de agente é:

1. list_figures para confirmar o alvo;
2. get_script e list_objects para entender a figura atual;
3. list_commands para inspecionar a sintaxe válida do dialeto 2D/3D ativo;
4. append_commands para mudanças aditivas, e set_script apenas quando linhas existentes precisam ser reescritas;
5. list_diagnostics para verificar o resultado e corrigir qualquer problema.

Chamar a API REST

Verifique primeiro o status e a descoberta de ferramentas:

curl http://127.0.0.1:14159/api/v1/status
curl http://127.0.0.1:14159/api/v1/tools

Crie dois pontos e um segmento:

curl -X POST http://127.0.0.1:14159/api/v1/tools/append_commands \
  -H "Content-Type: application/json" \
  -H "X-Eidograph-Client: my-agent" \
  -d '{"commands":"point A -2 0\npoint B 2 0\nsegment s A B"}'

As respostas usam um único envelope: {"ok":true,"result":...} em caso de sucesso ou {"ok":false,"error":...} em caso de falha. O cabeçalho opcional X-Eidograph-Client dá ao chamador um nome legível na atividade em Configurações.

A superfície atual pode ler e listar figuras, criar figuras, acrescentar ou substituir scripts, listar objetos/diagnósticos/comandos, selecionar um objeto na tela e exportar uma figura exposta como SVG, PNG, GIF ou MP4. As permissões de ferramentas e a exposição de figuras são aplicadas em cada chamada.

Configurar o Agente integrado

Salve vários modelos em Configurações › Agente e depois alterne entre eles pelo cabeçalho do Agente. O Eidograph suporta três famílias de protocolo:

• endpoints Chat Completions compatíveis com OpenAI;
• Anthropic Messages;
• Google Gemini / Vertex generateContent.

Cada modelo salvo tem um nome de exibição, provedor, URL base, chave de API e ID do modelo. Você pode digitar um ID manualmente se a descoberta de modelos falhar. Endpoints locais como Ollama e LM Studio também podem funcionar, mas o endpoint precisa permitir requisições de origem cruzada a partir do WebView do aplicativo (CORS).

O Agente integrado aceita imagens anexadas ou coladas, o que é útil para transformar uma foto de livro didático ou um esboço em uma construção. O suporte a visão depende do endpoint do modelo; uma requisição não suportada aparece como erro na conversa.

Nos apps para Windows e Android, o Agente também pode pesquisar na web: web_search busca um teorema, uma construção ou uma figura de referência pelo DuckDuckGo, e web_fetch lê uma página como texto ou examina uma imagem pela URL, por exemplo um diagrama a reproduzir. Somente sites públicos podem ser acessados. Essas duas ferramentas pertencem apenas ao Agente integrado; não fazem parte da superfície MCP/REST.

Permissões e limites de dados

• Agentes internos e externos não têm nenhum caminho privilegiado oculto; ambos usam as mesmas definições de ferramentas.
• Edições externas visam o projeto ativo e respeitam o estado de exposição de cada figura.
• As chaves de API nunca são gravadas no .eido. Os aplicativos Windows e Android usam armazenamento de credenciais protegido pelo sistema operacional.
• Os chats do Agente são excluídos do .eido por padrão e só são compartilhados quando Incluir chats do agente é ativado explicitamente.