Tucano

Visão geral

O Tucano Proxy é um debugger HTTP/HTTPS desktop, open source, escrito em Rust + Tauri 2. Roda 100% local, intercepta tráfego HTTP, HTTPS e WebSocket via MITM, e foi desenhado pra aguentar dezenas de milhares de requests sem travar.

Esta página é a referência completa: funcionalidades por área, sintaxe dos filtros, formatos de exportação, integração com agentes via MCP e o passo-a-passo de instalação do certificado raiz.

Funcionalidades

Captura

Proxy MITM local que intercepta HTTP, HTTPS e WebSocket (a conexão WS é encaminhada — inspector de frames individuais está no roadmap).

MITM em 127.0.0.1:8888
Porta configurável em Configurações → Proxy. Tudo roda local — nada sai da sua máquina.
CA raiz autogerada
Instalação one-click no trust store do OS. macOS via keychain (pede senha de admin), Windows via registry no store ROOT do usuário.
Toggle de system proxy
Um clique no status bar liga/desliga o proxy do sistema (macOS via networksetup, Windows via registry). Reverte sozinho ao sair.
SSL allowlist / blocklist
Pule MITM em hosts específicos. Útil para apps que fazem pinning ou domínios que você não quer interceptar.
Detecção do client app
Cada flow mostra qual processo originou a request (campo clientApp, em macOS e Windows).

Inspector

Painéis lado a lado de Headers, Body e Timing. Viewers auto-detectados pelo content-type.

Viewers
JSON tree, XML, HTML (com iframe e shadow preview), Raw, Hex, Image, Form (urlencoded + multipart).
Layout
Posicione o inspector como painel direito, painel inferior ou esconda completamente.
Busca dentro do body
⌘F abre busca local com highlight via CodeMirror.
Timing
DNS, conexão, TLS, TTFB, transferência — request e response side-by-side.

Lista de flows

Lista virtualizada (@tanstack/solid-virtual) que aguenta dezenas de milhares de capturas sem travar.

Colunas configuráveis
Arraste para reordenar, arraste a borda direita para redimensionar, duplo clique para auto-fit.
Marcas de cor
⌘0–⌘6 marca o flow com cores. Útil pra agrupar visualmente o fluxo de uma feature.
Notas inline
M abre o editor de nota por flow. Persistido na sessão .tucano.
Category tabs
HTTP, HTTPS, WebSocket, JSON, Form, XML, JS, CSS, GraphQL, Document, Media, Other. Atalhos 1–9 alternam entre elas.
Keep limit
Limite máximo de flows mantidos em memória — evita inchar em sessões longas.

Composer & Replay

Reproduza e modifique requests sem sair do app.

Composer
Monte uma request do zero (método, URL, headers, body) e dispare através do Tucano — o resultado aparece como um flow normal.
Replay
Re-dispara um flow existente, com sobrescritas opcionais em headers/body. O novo flow é logado e marcado como replay.

Sessões .tucano

Salva tudo em SQLite portátil — flows, bodies, notas, marcas de cor.

Salvar / abrir
⌘S salva como .tucano, ⌘O abre. Compartilhe com o time, anexe num ticket, abra meses depois — nada se perde.
Onde os dados ficam
Sessão ativa fica em SQLite local na app data dir do Tauri. Não há sync, nem nuvem, nem telemetria.

Compare & Find All

Compare (⌘D)
Selecione dois flows e abra um diff visual lado-a-lado — headers e body — pra entender o que mudou entre duas execuções.
Find All (⌘⇧F)
Busca global em URL, body, notas e headers de todos os flows capturados, com highlight ao vivo.

Filtros — DSL

A barra de filtros aceita uma DSL leve no padrão chave:valor. Tokens são combinados com AND. Use -chave:valor pra negar e aspas pra valores com espaço. Texto livre fora dos tokens vira busca full-text.

host:api.foo.com status:>=400 method:POST -path:/health
header:"x-trace=abc" duration:>500 mime:application/json
"invalid_credentials"  # texto livre vira busca em URL/body

Chave	Exemplo	Descrição
`host`	`host:api.foo.com`	Match parcial no hostname.
`method`	`method:POST`	Match exato no método.
`path`	`path:/users`	Match parcial no path.
`status`	`status:>=400`	Comparação numérica (>, >=, <, <=, =). Aceita aliases: ok, redirect, error, client, server, pending.
`scheme / proto`	`scheme:https`	http ou https.
`size`	`size:>1mb`	Soma de req+res. Aceita sufixos b, k, kb, m, mb.
`mime / type`	`mime:application/json`	Match parcial no content-type.
`header`	`header:"x-trace=abc"`	name=value, value opcional. Aspas pra valores com espaço.
`body`	`body:invalid_credentials`	Procura na request e response body.
`duration`	`duration:>500`	Em ms.
`ext`	`ext:json`	Extensão do path.
`port`	`port:8443`	Porta do destino.

Além da DSL, a barra de filtros também tem um modo Rules (UI multi-regra) — várias condições AND-combinadas, persistidas, sem precisar digitar.

Exportações

Por flow

Copie um único request em vários formatos:

cURL (bash/zsh)
cURL (Windows cmd)
PowerShell (Invoke-WebRequest)
JavaScript fetch
Python requests
HTTPie
Raw HTTP/1.1

Em lote

Selecione vários flows e exporte como:

Postman Collection v2.1 .postman_collection.json
HAR 1.2 .har
LLM Markdown .md

Exportação para LLM (Markdown)

O Tucano gera um tucano.llm.md com prompt customizável, linguagem-alvo e steps estruturados — feito pra colar direto numa conversa com Claude, GPT ou outro agente. Headers sensíveis são mascarados por padrão e placeholders cross-step ({var1}) carregam dicas de locator pra extração.

Linguagens-alvo

csharp — C# / .NET (HttpClient)
typescript — TypeScript (fetch)
python — Python (requests)
go — Go (net/http)
java — Java (HttpClient)
other — Outro / livre

Opções

redactSecrets (padrão: on) — mascara authorization, proxy-authorization, cookie, set-cookie, x-api-key, x-auth-token, x-csrf-token.
includeStructuredSteps (padrão: on) — gera a seção Steps (estruturado) com placeholders e locators.
includeResponseBodies (padrão: off) — inclui bodies limpos de HTML/JSON/XML pra o modelo derivar seletores.

tucano.llm.mdMarkdown

# Tucano — Fluxo HTTP capturado

> Você é um engenheiro de software experiente em TypeScript (fetch).
> Antes de gerar código, inspecione o repositório e siga o padrão
> usado para chamadas HTTP — não invente uma estrutura nova.

## Contexto
- Total de chamadas: 2
- Linguagem-alvo: TypeScript (fetch)
- Headers sensíveis mascarados: sim

## Steps (estruturado)

### 1. POST https://auth.example.com/login → 200 (124 ms)
| header | value |
| ------ | ----- |
| content-type | application/json |
| authorization | ***REDACTED*** |

### 2. GET https://api.example.com/me → 200 (88 ms)
| header | value |
| ------ | ----- |
| authorization | Bearer {var1}  <!-- from: step1 + locator: $.token -->

tucano-mcp — servidor MCP

O tucano-mcp é um servidor Model Context Protocol que expõe seus fluxos capturados a clientes LLM (Claude Desktop, Claude Code, Cursor, etc). Com a bridge MCP ligada no app, o agente passa a enxergar requests em tempo real — pode listar, ler bodies, refazer com overrides e compor requests novas, tudo via stdio.

Pré-requisitos

Tucano Proxy aberto com a bridge MCP ligada (Configurações → MCP).
Node.js 18+ no cliente que vai rodar o servidor MCP.
Token Bearer copiado de Configurações → MCP (é um UUID gerado na primeira execução; pode ser rotacionado).

Instalação

Recomendado via npx pra o cliente sempre pegar a versão mais recente. Cole no config MCP:

claude_desktop_config.jsonMCP

{
  "mcpServers": {
    "tucano": {
      "command": "npx",
      "args": ["-y", "tucano-mcp"],
      "env": {
        "TUCANO_TOKEN": "paste-the-token-from-tucano-settings"
      }
    }
  }
}

Variáveis de ambiente

TUCANO_TOKEN— obrigatório. Bearer token gerado pelo app.
TUCANO_URL— opcional. URL da bridge (padrão http://127.0.0.1:7878). Só mude se você alterou a porta.

Tools expostas

`tucano_status`	Status da bridge + proxy e contagem de flows. Sem parâmetros.
`tucano_list_flows`	Lista resumos dos flows capturados (sem bodies). Params: limit (1–1000), host, method, status, q, since (epoch-ms pra polling incremental).
`tucano_get_flow`	Flow completo, com bodies. Params: id.
`tucano_get_request_body`	Body da request decodificado (utf8 ou base64). Params: id.
`tucano_get_response_body`	Body da response decodificado (utf8 ou base64). Params: id.
`tucano_replay_flow`	Re-dispara um flow com overrides opcionais de headers/body; cria flow novo. Params: id, headers (substitui todos quando informado), body.
`tucano_compose_request`	Envia uma request nova pelo Tucano. Params: method, url (URL completa), headers, body, log (padrão true — false roda sem persistir).
`tucano_delete_flows`	Apaga flows por id. Params: ids (array).
`tucano_clear_flows`	Limpa todos os flows capturados — útil pra estabelecer baseline antes de uma automação. Sem parâmetros.
`tucano_start_capture`	Liga o proxy local e flipa o system proxy do OS pra o tráfego passar pelo Tucano. Params: port (opcional, padrão = porta atual, normalmente 8888).
`tucano_stop_capture`	Desliga o system proxy do OS e para o servidor proxy local. Sem parâmetros.
`tucano_export_as_curl`	Renderiza um ou mais flows como comandos curl prontos pra rodar — handoff pra dev/Claude Code reimplementar. Params: ids, includeHeaders (padrão true, inclui cookies/auth).
`tucano_export_as_code`	Renderiza flows como snippets de código. Params: ids, lang (fetch \| axios \| python, padrão fetch). Conjunto de linguagens mais enxuto que o export LLM completo.

Endpoints da bridge HTTP

Pra integrações além do MCP, a bridge é uma API HTTP local (axum) em 127.0.0.1:7878. Todos os endpoints exigem header Authorization: Bearer <token>.

GET	`/status`	{ running, port, systemProxyOn, flowsCount }
GET	`/flows`	Lista (sumários, sem bodies). Query: limit, host, method, status, q, since.
GET	`/flows/:id`	Flow completo (com bodies).
DELETE	`/flows`	Body { ids: string[] }. Apaga em lote.
POST	`/flows/:id/replay`	{ headers?, body? } → { id } do novo flow.
POST	`/compose`	{ method, url, headers?, body?, log? } → flow completo.
POST	`/clear`	Limpa todos os flows.
POST	`/capture/start`	{ port? } → { running, port }.
POST	`/capture/stop`	→ { running: false }.

Segurança

A bridge só aceita conexões em 127.0.0.1 e exige Bearer token. Trate o token como segredo — qualquer cliente com ele lê todo o seu tráfego capturado, incluindo bodies. Rotacione em Configurações → MCP → Rotate token a qualquer momento (e atualize o TUCANO_TOKEN no cliente).

Repositório npm

Atalhos

Em Linux/Windows, troque ⌘ por Ctrl. A lista completa também aparece em Configurações → Atalhos.

Iniciar / parar capturaSpace

Foco no filtro / adicionar token⌘K

Remover último filtro⌘⇧K

Buscar dentro do body⌘F

Find All (busca global)⌘⇧F

Compare dois flows selecionados⌘D

Salvar sessão .tucano⌘S

Abrir sessão .tucano⌘O

Limpar todos os flows⌘L

Selecionar tudo visível⌘A

Marcar flow com cor⌘0–⌘6

Adicionar / editar notaM

Apagar selecionadosDelete / Backspace

Trocar de category tab1–9

Abrir Configurações⌘,

Fechar inspector / Find AllEsc

Instalação do certificado raiz

Pra inspecionar HTTPS, o Tucano gera um CA local e instala no trust store do OS. Cada navegador/app tem suas particularidades — o resumo:

macOS

Configurações → Certificado → Install CA. Você digita a senha de admin e o Tucano roda security add-trusted-cert no keychain. Safari e Chrome passam a confiar imediatamente.

Windows

Install CA grava o certificado no store ROOT (Trusted Root Certification Authorities) do usuário atual via registry — sem prompt de admin. Edge e Chrome reaproveitam o store do sistema.

Firefox

Firefox tem store próprio. Em about:config, ative security.enterprise_roots.enabled = true, ou importe o certificado manualmente em Configurações → Privacidade e segurança → Certificados.

Roadmap

ComposerDisponível

Disponível desde v0.1.11

Replay com overridesDisponível

Disponível desde v0.1.11

Keep limitDisponível

Disponível desde v0.1.11

Linux bundles (AppImage, .deb)Disponível

Disponível na página de download

Breakpoints (pausar/editar request)Roadmap

AutoResponderRoadmap

WebSocket frame inspectorRoadmap

Hoje a conexão WS é encaminhada, sem inspeção de frames individuais.

gRPCRoadmap

Scripting (Lua/JS para reescrever requests)Roadmap

FAQ

Por que HTTPS não funciona?+

Você precisa instalar o CA do Tucano no trust store do OS (Configurações → Certificado → Install CA). Firefox usa seu próprio store: importe o certificado manualmente ou ative 'Use Enterprise roots' em about:config (security.enterprise_roots.enabled).

Como excluir um host do MITM?+

Adicione o host à SSL blocklist em Configurações → Certificado. Útil para apps com certificate pinning ou domínios que você simplesmente não quer interceptar.

O proxy do sistema continua ativo depois que eu fecho o app?+

Não — o Tucano reverte automaticamente ao sair. Se o app crashar, o toggle pode ficar ligado; nesse caso, abra de novo e desligue manualmente em Configurações.

Onde meus dados ficam?+

100% local. Sessão ativa fica em SQLite na app data dir do Tauri. Você pode salvar como arquivo .tucano (mesmo formato SQLite, portátil) pra compartilhar ou arquivar.

Tem versão para Linux?+

Tem — AppImage e .deb estão disponíveis na página de download, junto com macOS (Apple Silicon + Intel) e Windows x64.

Como rotacionar o token do MCP?+

Configurações → MCP → Rotate token. Lembre de atualizar TUCANO_TOKEN no config do seu cliente MCP depois.

Aparece um aviso de 'app não verificado' ao abrir?+

O app ainda não é code-signed. macOS: clique-direito → Abrir, ou xattr -cr /Applications/Tucano\ Proxy.app se ver 'is damaged'. Windows: SmartScreen → Mais info → Executar mesmo assim.

Docs do Tucano Proxy

Visão geral

Funcionalidades

Captura

Inspector

Lista de flows

Composer & Replay

Sessões .tucano

Compare & Find All

Filtros — DSL

Exportações

Por flow

Em lote

Exportação para LLM (Markdown)

Linguagens-alvo

Opções

tucano-mcp — servidor MCP

Pré-requisitos

Instalação

Variáveis de ambiente

Tools expostas

Endpoints da bridge HTTP

Segurança

Atalhos

Instalação do certificado raiz

macOS

Windows

Firefox

Roadmap

FAQ