LocalCan

Servidor MCP

Execute o servidor Model Context Protocol do LocalCan e conecte-o ao seu host MCP, com uma referência completa das ferramentas e opções.

localcan mcp executa um servidor Model Context Protocol via stdio. Um host MCP (Claude Code, Codex, Cursor, Claude Desktop e outros) o inicia e chama as ferramentas do LocalCan para ler o tráfego capturado, gerenciar URLs Públicas (túneis) e publicar Snapshots. O LocalCan deve estar em execução para que as ferramentas retornem dados, então abra o aplicativo desktop ou execute localcan start -d primeiro.

Ferramentas

O servidor expõe vinte e seis ferramentas. A leitura funciona imediatamente. As dezesseis ferramentas que alteram coisas precisam de acesso de escrita, que está desativado por padrão (veja as opções abaixo). Criar ou adicionar uma URL Pública exige uma licença ativa. Publicar um Snapshot e proteger uma URL com senha exigem um plano de assinatura, então uma licença perpétua é recusada mesmo que ainda possa abrir URLs Públicas. Sem licença, as ferramentas restritas retornam uma mensagem clara de ativação, enquanto pausar, retomar e remover URLs existentes ainda funciona.

Tráfego:

Ferramenta	O que faz	Parâmetros
get_status	Informa se a captura está ativa e quanto tráfego está em buffer.	nenhum
enable_capture	Ativa a captura. A captura está desativada por padrão e é redefinida quando o daemon reinicia.	nenhum
list_traffic	Lista as trocas recentes, das mais novas para as mais antigas.	last (padrão 20), host substring, project id, method, status (código exato ou uma classe como 5xx)
get_exchange	Retorna uma troca pelo id.	id obrigatório (id completo ou qualquer prefixo único), format um de markdown, curl, http, har, json (padrão markdown), include_response (padrão true)

Uma troca é a requisição que o LocalCan encaminhou para o seu backend, não uma cópia byte a byte da requisição original do cliente. Veja Tráfego para o modelo de dados.

URLs Públicas:

Ferramenta	O que faz	Parâmetros
list_services	Lista os serviços que o LocalCan atende, cada um com um identificador <project>/<service>, seu destino local e contagem de endpoints.	nenhum
list_public_urls	Lista suas URLs Públicas, incluindo as pausadas, cada uma com seu estado (ativo, pausado, erro, iniciando, inativo) e o que atende (ao vivo, snapshot, nenhum). Cada linha também traz access: nenhum, senha, link ou um nome de política da equipe. Uma URL estacionada que atende um Snapshot aparece como estado pausado mas atendendo snapshot, então responda "o link está no ar?" com base no atendimento, não no estado.	nenhum
get_public_url_status	Informa o estado de uma URL Pública, o que ela atende (ao vivo, snapshot, nenhum) e sua proteção access, mesmo vocabulário da lista, além do destino local e quaisquer regras de cabeçalho de requisição.	url obrigatório
create_public_url	Cria uma URL Pública para uma porta local em um novo projeto e retorna o endereço atribuído, como my-app-12.localcan.dev. Leva alguns segundos. Se o túnel for rejeitado (por exemplo, o limite de URLs Públicas do seu plano) ou expirar, a tentativa é revertida e nada fica para trás. Para um link que permanece acessível depois que sua máquina fica offline, adicione um Snapshot com add_snapshot. Para um aplicativo servido como host virtual, passe host e uma regra de Host em headers (veja abaixo).	port obrigatório, name opcional (molda o endereço), protocol http ou tcp (padrão http), host opcional (padrão localhost), headers opcional (regras de cabeçalho de requisição, cada {name, value, mode?, enabled?})
add_public_url	Adiciona uma URL Pública a um serviço que você já configurou. O protocolo segue o destino do serviço, então um destino tcp:// recebe um túnel TCP. Mesma reversão em caso de falha que a criação.	identificador service obrigatório
pause_public_url	Coloca uma URL Pública offline mantendo seu endereço, para que possa ser retomada depois. Um endereço gerado *.localcan.dev permanece reservado por 7 dias enquanto pausado; domínios personalizados nunca expiram.	url obrigatório
resume_public_url	Traz uma URL Pública pausada de volta ao ar no mesmo endereço.	url obrigatório
remove_public_url	Remove permanentemente uma URL Pública. Um endereço gerado é liberado, um domínio personalizado continua seu e pode ser adicionado novamente. Remover o último endpoint de um serviço também remove o serviço e o projeto esvaziados. Para manter o endereço mas parar de atender um Snapshot, use remove_snapshot. Marcada como destrutiva, então os hosts normalmente pedem confirmação.	url obrigatório
set_public_url_headers	Substitui as regras de cabeçalho de requisição em uma URL Pública, os cabeçalhos que o LocalCan define antes de encaminhar para o seu aplicativo. Passe a lista completa; uma lista vazia as limpa. get_public_url_status informa as regras no mesmo formato (mode definir, adicionar ou remover, e enabled), então uma lista lida ali pode ser editada e gravada de volta.	url e headers obrigatórios

Um aplicativo servido como host virtual (um site Laravel Herd ou Valet em myapp.test, um nginx server_name) precisa ver seu próprio nome de host, e o LocalCan encaminha o nome de host público por padrão. Passe host e uma regra de Host, headers: [{"name": "Host", "value": "{{target_host}}"}], e o aplicativo atende o site certo. Os modelos de valor são os de Cabeçalhos.

Snapshots (veja Snapshots):

Ferramenta	O que faz	Parâmetros
publish_snapshot	Publica uma pasta como Snapshot em uma nova URL Pública, para que permaneça acessível depois que sua máquina ficar offline. Aponte para a saída estática compilada quando possível, ou para a raiz do projeto para o LocalCan compilar (as dependências já devem estar instaladas). Retorna o novo endereço. Sempre cria uma nova URL, então para atualizar uma prévia existente use update_snapshot.	path obrigatório (absoluto), name opcional (molda o endereço)
add_snapshot	Adiciona um Snapshot a uma URL Pública que você já tem, para que um link existente continue atendendo offline. Aponta para update_snapshot se a URL já tiver um.	url e path obrigatórios
update_snapshot	Republica o Snapshot em uma URL Pública. Omita path para recompilar da mesma fonte, ou passe para apontar para outra pasta. Aponta para add_snapshot se a URL não tiver nenhum.	url obrigatório, path opcional
remove_snapshot	Remove o Snapshot de uma URL Pública. A URL permanece reservada e continua atendendo ao vivo enquanto seu túnel estiver ativo. Marcada como destrutiva.	url obrigatório
get_snapshot_status	Informa o Snapshot de uma URL Pública: sua pasta de origem, quando foi publicado, se a origem mudou desde então (desatualizado) e se a URL atende ao vivo ou o snapshot agora. Também traz os comentários de revisão sobre ele (estado e contagens) e, uma vez que os comentários estiverem ativos, o número da versão do Snapshot.	url obrigatório

Controle de acesso (veja Controle de acesso):

Ferramenta	O que faz	Parâmetros
set_password	Protege uma URL Pública com senha para que apenas pessoas que tenham a senha possam abri-la. Aplicada nos servidores do LocalCan, então também cobre um Snapshot nessa URL. Gera uma senha forte a menos que você passe uma, e a retorna para que você possa compartilhá-la. Exige um plano de assinatura.	url obrigatório, password opcional (omitir para gerar uma)
clear_access	Remove a proteção por senha, tornando a URL pública novamente. Não remove a URL nem seu Snapshot. Marcada como destrutiva, então os hosts normalmente pedem confirmação.	url obrigatório
get_access_status	Informa a proteção de uma URL Pública e retorna sua senha atual quando ela está protegida por senha. A senha nunca é retornada por list_public_urls, apenas aqui.	url obrigatório

Comentários (os comentários de revisão que os revisores deixam em um Snapshot, veja Comentários):

Ferramenta	O que faz	Parâmetros
list_comments	Lista os tópicos de comentários no Snapshot de uma URL Pública com suas respostas. Cada tópico traz o caminho da página, a âncora (um seletor CSS e a posição do pino nesse elemento), a viewport e o navegador do revisor, e a versão do Snapshot em que foi deixado. Nunca marca nada como lido.	url obrigatório, status aberto, resolvido ou todos (padrão aberto), page caminho, version número
reply_comment	Publica uma resposta em um tópico sob o nome da sua conta. Os revisores no tópico a recebem por e-mail, a menos que as notificações de resposta estejam desativadas para a equipe ou eles tenham cancelado a inscrição. Apenas respostas; novos tópicos são fixados na página.	url, comment_id, body obrigatórios
resolve_comment	Marca um tópico como resolvido, respostas incluídas.	url e comment_id obrigatórios
reopen_comment	Reabre um tópico resolvido.	url e comment_id obrigatórios
set_comments	Alterna os comentários em um Snapshot: ativado, pausado (os tópicos existentes permanecem legíveis, sem novos) ou desativado. Exige uma URL protegida e um plano de assinatura.	url e state obrigatórios

O ciclo de feedback

As ferramentas se encadeiam em um ciclo que um agente pode executar sozinho: list_comments para ler os tópicos abertos, editar a origem, update_snapshot para publicar a nova versão, depois reply_comment e resolve_comment por tópico. Os comentários são transferidos para a nova versão, então o revisor vê a resposta no mesmo pino. O servidor informa isso ao agente por conta própria. Suas instruções MCP, que os hosts adicionam ao prompt do agente, descrevem o ciclo, a configuração das rodadas de revisão (publish_snapshot, set_password, set_comments) e a receita do host virtual. Duas coisas que um agente não pode fazer: iniciar um tópico (os revisores os fixam na página) e marcar tópicos como lidos (não lido é o estado da sua própria caixa de entrada no aplicativo).

Conectando um agente

Como você conecta depende de como o agente é executado. Agentes de terminal (Claude Code, Codex) herdam o PATH do seu shell, então um comando localcan simples funciona. Aplicativos GUI (Cursor, Claude Desktop, VS Code e outros) não carregam o PATH do seu shell, então precisam do caminho absoluto para o binário, por exemplo /Users/you/.localcan/bin/localcan. As Configurações do aplicativo desktop podem copiar uma configuração pronta com o caminho correto preenchido, que também é o caminho confiável no Windows.

Claude Code

claude mcp add --scope user localcan -- localcan mcp

A flag --scope user registra o servidor para todos os projetos. Remova-a para registrá-lo apenas no projeto atual.

Codex

codex mcp add localcan -- localcan mcp

Isso grava o servidor em ~/.codex/config.toml. Para o aplicativo desktop do Codex ou a extensão do IDE, passe o caminho absoluto no lugar de localcan.

Cursor, Claude Desktop e Windsurf

Eles compartilham o mesmo formato mcpServers:

{
  "mcpServers": {
    "localcan": {
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

Adicione-o ao arquivo correto e recarregue:

• Cursor: ~/.cursor/mcp.json, depois habilite o servidor nas Configurações.
• Claude Desktop: claude_desktop_config.json (Configurações, Desenvolvedor, Editar Configuração), depois saia e reinicie.
• Windsurf: ~/.codeium/windsurf/mcp_config.json, depois atualize o painel MCP.

VS Code

O VS Code (modo agente do Copilot) usa uma chave servers com um tipo explícito. Adicione isto a .vscode/mcp.json no seu workspace:

{
  "servers": {
    "localcan": {
      "type": "stdio",
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

Você também pode executar code --add-mcp com o mesmo objeto de servidor.

Zed

O Zed usa context_servers em seu settings.json:

{
  "context_servers": {
    "localcan": {
      "source": "custom",
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

Você também pode adicioná-lo nas configurações do Painel do Agente.

Acesso do agente, redação e acesso de escrita

Todos os três são controlados no aplicativo desktop em Configurações (seção "AI Agents (MCP)"), ou pelo terminal: localcan mcp enable / disable para acesso do agente, localcan mcp redact <on|off> para redação, localcan mcp access <read_only|read_write> para acesso de escrita e localcan mcp status para ver o estado atual.

• O acesso de agentes está ativado por padrão. Desative-o para impedir que agentes usem o LocalCan por completo. O servidor ainda inicia, mas toda ferramenta retorna uma mensagem clara de "acesso desativado" até você reativá-lo.
• A redação está ativada por padrão para agentes. Cabeçalhos sensíveis (Authorization, cookies, chaves de API) são removidos das respostas das ferramentas. URLs e corpos não são redigidos. Desative-a para permitir que seu próprio agente receba valores brutos.
• O acesso de escrita está desativado por padrão. A leitura funciona sem ele, mas as ferramentas de escrita retornam uma mensagem clara de somente leitura até você ativá-lo, no aplicativo ("Allow agents to create and change Public URLs") ou com localcan mcp access read_write. Ativar o acesso de agentes não concede acesso de escrita. São interruptores separados. Cada chamada de escrita é registrada na saída de diagnóstico do servidor, que seu host captura, para que você tenha um registro do que um agente alterou. Uma senha passada para set_password é mascarada nesse registro.

Quando uma ferramenta recusa

• Toda ferramenta gera erro com uma mensagem de conexão com o daemon: o LocalCan não está em execução. Abra o aplicativo de desktop ou execute localcan start -d.
• list_traffic não retorna nada: a captura está desativada (está desativada por padrão e é redefinida quando o daemon reinicia). Execute localcan traffic enable ou deixe o agente chamar enable_capture.
• "MCP access is disabled": o acesso de agentes está desativado. Execute localcan mcp enable ou alterne a opção em Configurações.
• "MCP is read-only": a ferramenta altera coisas e o acesso de escrita está desativado. Execute localcan mcp access read_write ou ative a opção em Configurações.
• "public URLs require a license": criar e adicionar uma Public URL exige uma licença ativa. Ative uma no aplicativo ou com localcan license activate <key>.
• "need a subscription plan": Snapshots e Access control são exclusivos para assinatura. Uma licença perpétua pode abrir Public URLs, mas não pode publicar um Snapshot ou definir uma senha. Assine pelo seu dashboard e tente novamente.
• "already has a snapshot" ou "has no snapshot yet": use a ferramenta que a mensagem nomeia. add_snapshot anexa um Snapshot a uma URL que não tem nenhum, update_snapshot atualiza um que já tem.
• "Snapshot limit reached": seu plano limita quantas Public URLs podem servir um Snapshot ao mesmo tempo. A mensagem lista as URLs que já estão usando um slot, que você pode atualizar com update_snapshot em vez de publicar um novo.
• "Comments need a protected URL": set_comments foi chamado em uma URL sem Access control. Execute set_password primeiro.
• "Your account has no display name": uma resposta precisa de um nome para ser publicada. Defina-o no dashboard ou responda uma vez na página do Snapshot após abri-lo como proprietário pelo aplicativo.
• O host mostra o servidor como falho ou sem ferramentas: um aplicativo GUI não consegue encontrar localcan no PATH. Use o caminho absoluto, mais fácil via copiar configuração nas Configurações.