# Visão geral

O `@tunnelhub/mcp` conecta clientes compatíveis com Model Context Protocol ao TunnelHub para investigação operacional e leitura de recursos da plataforma.

## Casos de uso

Use o MCP para:

* autenticar no TunnelHub pelo navegador;
* consultar a sessão atual e o ambiente ativo;
* listar as sessões salvas localmente;
* listar pacotes, systems, automações e Tabelas De/Para;
* localizar execuções por período;
* abrir logs, traces e resumos de execução;
* consultar APIs, planos de uso, chaves de API, clientes e servidores de recursos;
* investigar consumo e estatísticas do tenant.

O uso mais valioso hoje costuma estar em investigação de execuções e análise de logs operacionais.

## Perfil da ferramenta

O MCP atual é principalmente orientado a leitura e suporte operacional. Ele não substitui o portal para modelagem completa de recursos.

Em outras palavras, ele é ideal para:

* investigar incidentes;
* responder perguntas operacionais rapidamente;
* resumir execuções e falhas;
* consultar dados de ambiente sem navegar manualmente por múltiplas telas.

## Instalação local

O uso principal é via `npx`:

```bash
npx -y @tunnelhub/mcp@latest
```

Se você estiver desenvolvendo localmente:

```bash
pnpm install
pnpm build
node dist/index.js
```

## Modo de execução

O pacote público atual é usado via `stdio`, que é o modo esperado pelos clientes MCP no desktop.

Para a maioria dos times, esse continua sendo o caminho principal.

## Como a autenticação funciona hoje

O fluxo principal continua sendo via ferramentas de sessão do próprio MCP. No primeiro uso, o cliente chama `login_tunnelhub`, o MCP abre o navegador local, você faz login no TunnelHub e a sessão fica salva localmente.

Para o primeiro login, informe `accountName` da empresa. Se houver ambiguidade ou o nome não resolver a empresa correta, repita o fluxo com `tenantId`.

No conjunto público atual, as ferramentas de sessão registradas são:

* `login_tunnelhub`
* `current_session_tunnelhub`
* `list_sessions_tunnelhub`
* `list_environments_tunnelhub`
* `switch_environment_tunnelhub`
* `logout_tunnelhub`

Depois do login, as demais ferramentas passam a usar a sessão ativa e o ambiente atual. `list_sessions_tunnelhub` permite inspecionar as sessões salvas localmente, e `logout_tunnelhub` permite remover a sessão atual ou uma sessão específica.

## Exemplos de perguntas úteis

Alguns exemplos de uso em linguagem natural:

* "Faça login no TunnelHub"
* "Qual sessão está ativa?"
* "Quais sessões estão salvas localmente?"
* "Liste os ambientes disponíveis"
* "Encontre execuções com erro da automação X nas últimas 24 horas."
* "Resuma a execução Y e destaque os principais erros."
* "Mostre os systems do ambiente atual relacionados ao pacote Z."
* "Quais APIs tiveram chamadas com status 500 hoje?"

## Limites práticos

O MCP foi desenhado para operação e investigação, então vale considerar alguns limites:

* muitas consultas dependem de intervalo de tempo explícito;
* detalhes de execução exigem identificadores específicos;
* parte das respostas reflete o backend atual, incluindo nomes técnicos do produto;
* algumas respostas podem incluir dados sensíveis, como payloads de logs de API.

## Próximos passos

* Leia [Runtime e autenticação](https://docs.tunnelhub.io/mcp/runtime-and-auth).
* Leia [Catálogo de ferramentas](https://docs.tunnelhub.io/mcp/tools).
* Leia [Investigando execuções](https://docs.tunnelhub.io/mcp/investigating-executions).