Como o servidor MCP do Guida funciona

20 de janeiro de 2025 · 8 min de leitura ·

técnico

O Guida vem com um servidor Model Context Protocol (MCP) integrado. É isso que permite que uma IA externa, como Claude Code, Cursor ou qualquer cliente compatível com MCP, controle o navegador. Ele é a ponte entre dizer a uma IA “quero raspar esta página” e as consultas reais ao DOM, cliques e armazenamento de dados que fazem isso acontecer.

Este post é um mergulho técnico em como ele funciona. Vamos cobrir o protocolo, a camada de transporte, como as ferramentas são registradas e o modelo de segurança em três camadas que garante que a IA não possa fazer nada sem seu conhecimento e consentimento.

O que é MCP, em resumo

MCP é um protocolo JSON-RPC para conectar modelos de IA a ferramentas externas. A IA envia uma solicitação como “chame a ferramenta Navigate com url: https://example.com”, o servidor executa e retorna o resultado. O modelo nunca toca o navegador diretamente: ele só vê o contrato de entrada e saída da ferramenta.

O protocolo define três primitivas:

Tools: funções que a IA pode chamar, como navegar, clicar e extrair
Resources: dados que a IA pode ler, como guias abertas e conteúdo da página
Prompts: modelos reutilizáveis para operações comuns

O Guida implementa as primitivas de ferramentas e recursos. Ele expõe mais de 100 ferramentas para automação de navegador, armazenamento de dados, pesquisa e mais.

Transporte: HTTP local

O MCP aceita vários transportes. O Guida usa transporte HTTP local: o servidor executa uma instância Kestrel embutida em http://127.0.0.1:9315.

A escolha de HTTP em vez de stdio tem razões práticas: o Guida é um aplicativo desktop WPF, não uma ferramenta CLI. Não há stdin/stdout para encadear. HTTP também permite que clientes MCP externos se conectem enquanto a UI do navegador, o estado de aprovação, o histórico de tarefas e os painéis do espaço de trabalho continuam visíveis.

Para clientes HTTP streamable atuais, o endpoint útil é a raiz do servidor:

http://127.0.0.1:9315/

O handshake segue o padrão MCP: o cliente inicializa, o servidor retorna as capacidades disponíveis, depois o cliente descobre ferramentas e começa a fazer chamadas.

Client → initialize
         {"jsonrpc": "2.0", "method": "initialize", ...}

Server → capabilities
         {"jsonrpc": "2.0", "id": 1, "result": {...}}

Client → tools/list
Client → tools/call

Registro de ferramentas

As ferramentas são registradas em McpServerService.cs usando o SDK MCP para .NET. Cada ferramenta tem nome, descrição, JSON Schema para parâmetros e um handler assíncrono.

Aqui estão algumas ferramentas representativas entre as mais de 100 disponíveis:

Ferramenta	Descrição
`Navigate`	Navega a guia ativa até uma URL
`Click`	Clica em um elemento por seletor CSS
`GetElements`	Consulta elementos do DOM e extrai atributos
`Screenshot`	Captura a viewport visível como PNG
`ExecuteScript`	Executa um script `g.*` no motor de scripting do aplicativo
`StoreGet` / `StorePut`	Lê e grava no armazenamento do espaço de trabalho
`QueueEnqueue` / `QueueDequeue`	Gerencia filas de trabalho
`SearchQuery`	Faz pesquisa de texto completo em documentos indexados

Por baixo, a maioria das ferramentas delega aos mesmos serviços que alimentam a API de scripting g.*. Navigate chama o mesmo BrowserAutomationService.NavigateAsync() que g.nav.navigateToUrl() usa. A camada MCP é um adaptador fino que mapeia solicitações JSON-RPC para chamadas de serviço e formata os resultados.

Isso significa que scripts e ferramentas de IA têm as mesmas capacidades, com uma exceção crítica que veremos na seção de segurança.

Segurança em três camadas

É aqui que o Guida se diferencia da maioria dos servidores MCP. A IA é poderosa, mas não é confiável por padrão. Toda ação passa por três camadas de segurança antes de chegar ao navegador.

Camada 1: lista de permissões de domínios

Antes que a IA possa navegar para qualquer URL, o domínio precisa estar na lista de permissões. O Guida oferece três níveis:

Por sessão: domínios aprovados que expiram quando você fecha o aplicativo
Por espaço de trabalho: domínios listados em domains.json na pasta do espaço de trabalho
Global: domínios sempre permitidos, configurados nas preferências

Se a IA tentar navegar para um domínio que não está permitido, a chamada da ferramenta falha com uma mensagem de erro clara. A IA vê a rejeição e pode explicar o que aconteceu.

Curingas funcionam: *.example.com permite todos os subdomínios. A lista de permissões se aplica apenas à navegação por script; você pode navegar manualmente para qualquer lugar.

Camada 2: aprovação de ferramentas

Mesmo em um domínio permitido, chamadas de ferramentas monitoradas exigem sua aprovação explícita. Quando a IA quer clicar em um botão ou executar um script, o Guida mostra:

O nome exato da ferramenta que está sendo chamada
Os parâmetros exatos: URL, seletor, código do script e assim por diante
Opções para aprovar uma vez, aprovar nesta sessão ou negar

É o mesmo modelo de permissão que você esperaria de um aplicativo móvel pedindo acesso à câmera, exceto que é por ação, não por instalação. Você pode confiar em uma ferramenta durante a sessão se cansar de clicar em aprovar, ou revisar cada chamada individualmente.

O Approval Center mostra os parâmetros reais, não um resumo. Se a IA quiser chamar Click com o seletor button.delete-account, você verá esse seletor exato antes da execução.

Camada 3: trilha de auditoria

Toda chamada de ferramenta é registrada em mcp-audit.db, um banco LiteDB separado que a IA não consegue acessar. O registro de auditoria captura:

Nome da ferramenta e parâmetros, nos primeiros 4000 caracteres
Resultado ou erro, nos primeiros 2000 caracteres
Duração da execução
Carimbo de data/hora e ID da sessão

O painel MCP History no aplicativo mostra o registro de auditoria em tempo real. Você pode pesquisar, filtrar por erros e abrir chamadas individuais para ver os parâmetros e resultados JSON completos.

A propriedade de segurança principal: a IA não consegue ler nem apagar a própria trilha de auditoria. Não há ferramentas MCP que exponham o banco de auditoria. Isso significa que mesmo uma IA afetada por prompt injection não consegue apagar seus rastros.

Isolamento de credenciais

Mais uma fronteira de segurança merece destaque. O Guida tem um painel Secrets onde você armazena chaves de API, senhas e tokens, criptografados com Windows DPAPI. Scripts podem ler credenciais via g.secrets.getSecret(name), mas scripts originados por MCP não podem.

Quando um script é iniciado por uma ferramenta MCP, como ExecuteScript, o Guida o marca com a origem Mcp. Qualquer chamada a g.secrets.getSecret() feita por um script de origem MCP retorna erro. Isso quebra a cadeia de exfiltração:

AI calls ExecuteScript → script calls g.secrets.getSecret("api-key")
                        → BLOCKED (MCP origin detected)

Sem isso, uma IA afetada por prompt injection poderia executar um script que lê sua chave de API, gravá-la em g.store e depois ler o armazenamento via MCP. A verificação de origem impede o primeiro passo.

Outras operações de credenciais, como listar nomes e definir valores, são permitidas: apenas a leitura de valores descriptografados é bloqueada. Isso permite que a IA ajude a gerenciar credenciais sem jamais ver os valores reais.

Ferramentas customizadas

Além das mais de 100 ferramentas integradas, você pode definir ferramentas HTTP customizadas no tools.json de um espaço de trabalho:

{
  "tools": [
    {
      "name": "GetWeather",
      "description": "Get current weather for a city",
      "endpoint": "https://api.weather.example/v1/current",
      "method": "GET",
      "parameters": {
        "city": { "type": "string", "description": "City name", "required": true }
      },
      "headers": {
        "Authorization": "Bearer {{secrets.WEATHER_API_KEY}}"
      }
    }
  ]
}

Observe o template {{secrets.WEATHER_API_KEY}}. O valor real da credencial é injetado pelo servidor no momento da chamada; a IA nunca o vê. Isso permite dar à IA acesso a APIs autenticadas sem expor credenciais.

Ferramentas customizadas passam pelo mesmo fluxo de aprovação que as ferramentas integradas. A IA vê o esquema da ferramenta, propõe uma chamada, e você aprova ou nega.

Resumo da arquitetura

Veja como as peças se encaixam:

┌──────────────────────┐
│   AI Client          │  Claude Code, Cursor, etc.
│   (MCP Client)       │
└──────────┬───────────┘
           │ MCP over local HTTP
           │
┌──────────▼───────────┐
│   Guida MCP Server   │  Embedded Kestrel on 127.0.0.1:9315
│                      │
│  ┌─ Domain Filter ─┐ │  Layer 1: allowed-domain check
│  ├─ Approval Center┤ │  Layer 2: User approves/denies
│  ├─ Audit Logger  ─┤ │  Layer 3: Record to mcp-audit.db
│  └─ Tool Handler  ─┘ │  Execute via shared services
│                      │
└──────────┬───────────┘
           │ Service calls
           │
┌──────────▼───────────┐
│   Shared Services    │  BrowserAutomation, Store, Queue,
│                      │  Search, Network, History, etc.
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│   Browser / WebView2 │  Chromium-based browser engine
└──────────────────────┘

O servidor MCP é uma camada adaptadora fina. Ele não duplica lógica de negócio: mapeia JSON-RPC para os mesmos serviços usados por scripts. As camadas de segurança, como filtro de domínio, aprovação e auditoria, são inseridas como middleware no pipeline MCP.

Conectando um cliente

Para conectar Claude Code ou outro cliente MCP ao Guida, adicione isto à configuração do cliente MCP:

{
  "mcpServers": {
    "guida": {
      "url": "http://127.0.0.1:9315/"
    }
  }
}

Pronto. O cliente descobre as ferramentas disponíveis pelo método tools/list e começa a fazer chamadas. O Approval Center do Guida cuida das solicitações monitoradas.

Para mais detalhes sobre as ferramentas disponíveis e a configuração do espaço de trabalho, consulte a documentação de Integração MCP e o guia de Ferramentas customizadas.