toolhive MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Servidores MCP isolados em contêiner (Docker / Kubernetes)
Registro MCP verificado e curado com configurações predefinidas
Instalação de um clique em Claude Desktop, Cursor, VS Code
SSO, segredos criptografados, log de auditoria, OpenTelemetry
Aplicativo de desktop, web, CLI e Operador Kubernetes

Demo ao vivo

Como fica na prática

toolhive.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "toolhive",
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "toolhive": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/stacklok/toolhive"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add toolhive -- TODO 'See README: https://github.com/stacklok/toolhive'

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: toolhive

Como instalar um MCP da comunidade sem confiar em scripts `npx -y` aleatórios

👤 Engenheiros preocupados com segurança ⏱ ~10 min beginner

Quando usar: Você deseja que o GitHub MCP seja executado localmente, mas não quer dar acesso irrestrito ao sistema de arquivos.

Pré-requisitos

Docker Desktop — docker.com
Aplicativo de desktop ToolHive — stacklok.com/download

Fluxo

Abra ToolHive, procure no registro

Instale 'github' do registro ToolHive.✓ Copiado

→ Contêiner baixado, prompt de configuração para GITHUB_TOKEN
Configure automaticamente seu cliente

Clique em 'Conectar ao Claude Desktop'.✓ Copiado

→ Configuração do Claude Desktop atualizada; reinicialização necessária
Verifique o isolamento

Confirme que o contêiner tem apenas as variáveis de ambiente definidas e nenhuma montagem do sistema de arquivos do host.✓ Copiado

→ Inspecione a configuração do contêiner na interface do ToolHive

Resultado: Um MCP em sandbox com acesso de privilégio mínimo à sua máquina.

Armadilhas

MCPs do sistema de arquivos precisam de uma montagem — a ausência padrão é muito restritiva — Adicione uma montagem com escopo (por exemplo, apenas ~/Projects) em vez de home completo

Como implantar MCPs no Kubernetes para uma equipe de plataforma

👤 Engenheiros de plataforma ⏱ ~60 min advanced

Quando usar: Você deseja disponibilidade de MCP padronizada em toda a organização.

Pré-requisitos

Kubernetes cluster + cluster-admin — EKS/GKE/AKS existente ou kind para desenvolvimento
CRDs do Operador ToolHive instalados — kubectl apply -f os manifestos fornecidos pela Stacklok

Fluxo

Declare recursos MCPServer

kubectl apply -f mcp-github.yaml — registre declarativamente um GitHub MCP com segredos com escopo.✓ Copiado

→ Pod em execução; Portal a lista
Expor para usuários através do Portal

Engenheiros fazem login no Portal com SSO e instalação de um clique em seu cliente.✓ Copiado

→ Configurações por usuário geradas automaticamente

Resultado: Catálogo central + instalação por usuário; auditável.

Armadilhas

MCPs Stdio não funcionam bem com Kubernetes exposto à rede — Prefira MCPs HTTP Streamable para k8s; use o gateway para os stdio

Como produzir uma trilha de auditoria de todas as chamadas de ferramenta MCP

👤 Equipes de conformidade, segurança ⏱ ~30 min intermediate

Quando usar: Sua organização precisa de 'quem chamou qual ferramenta quando' para SOC2 ou política interna.

Fluxo

Habilitar exportação do OpenTelemetry

Nas configurações do ToolHive, defina o endpoint OTLP para seu coletor.✓ Copiado

→ Traces aparecem em seu backend
Marcar por usuário

Habilitar propagação de identidade por usuário via SSO.✓ Copiado

→ Cada trace tem id do ator

Resultado: Log de auditoria por usuário, por ferramenta.

Combinações

Combine com outros MCPs para 10× de alavancagem

toolhive + mcphub

Use ToolHive para isolamento, MCPHub para roteamento de vários servidores

Execute cada MCP em seu próprio contêiner ToolHive e exponha-os através de grupos MCPHub.✓ Copiado

toolhive + unla

Combine MCPs executados por ToolHive com a conversão REST-para-MCP da Unla

Registre nossa API interna convertida por Unla no ToolHive para que seja executada containerizada com SSO.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
(platform) registry-install	mcp_name	Instalar um MCP verificado	free
(platform) gateway-proxy	Transporte + política de autenticação	Fronteie seus MCPs com política	free
(platform) runtime-isolate	Especificação de contêiner	Execução em sandbox	free + custo de infra

Custo e limites

O que custa rodar

Cota de API: Nenhuma na camada de plataforma
Tokens por chamada: Sobrecarga mínima
Monetário: Desktop + CLI + Operador open-source são gratuitos. Planos Enterprise para suporte/conformidade.
Dica: Comece com o nível gratuito; atualize apenas se precisar de SLAs dedicados ou SSO/RBAC avançado.

Segurança

Permissões, segredos, alcance

Escopos mínimos: Por MCP: variáveis de ambiente e montagens de privilégio mínimo SSO para implantações em equipe

Armazenamento de credenciais: Gerenciador de segredos criptografados integrado ao ToolHive

Saída de dados: Determinado por MCPs downstream; ToolHive adiciona telemetria se configurado

Nunca conceda: Não conceda automaticamente montagens do sistema de arquivos além do que cada MCP precisa

Executar muitos MCPs em um único contêiner anula o isolamento; um por contêiner.

Solução de problemas

Erros comuns e correções

Contêiner inicia e depois sai imediatamente

Verifique se as variáveis de ambiente necessárias do MCP estão definidas (por exemplo, GITHUB_TOKEN). Visualize os logs na interface do ToolHive.

Claude Desktop não consegue encontrar o servidor após a instalação

Reinicie Claude Desktop — as alterações de configuração só são carregadas na inicialização.

Falha na instalação de CRD do Operador K8s

Certifique-se de ter cluster-admin e versão k8s suportada (>= 1.27).

Verificar: kubectl version

Traces OTLP ausentes

O endpoint do Coletor deve aceitar OTLP/HTTP ou OTLP/gRPC; confirme a correspondência de protocolo.

Alternativas

toolhive vs. outros

Alternativa	Quando usar	Troca
MCPHub	Você deseja agregação de vários servidores mais do que isolamento de contêiner	Não focado em runtime de contêiner
Docker MCP Toolkit	Você prefere a ferramenta integrada própria do Docker	Registro menos curado

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills