FusionAL

🚀 FusionAL — Gateway de Governança MCP Auto-hospedado

Sua equipe conectou 10 servidores MCP. E agora?
🌐 fusional.dev • 📧 jrm@fusional.com • 🗓️ Agende uma Chamada

MCP é poderoso. Implantação empresarial de MCP é um problema completamente diferente.

Cada servidor que você conecta carrega seu manifesto completo de ferramentas para o contexto do Claude antes de processar um único token da sua solicitação. Com 84 ferramentas em vários servidores, isso significa 15.540 tokens consumidos no início da sessão — antes que sua equipe tenha perguntado qualquer coisa. Em escala, isso é custo, latência e uma superfície de auditoria que ninguém consegue explicar para o jurídico.

FusionAL é um gateway de governança MCP auto-hospedado que fica entre seus clientes de IA e seus servidores de ferramentas. Um único endpoint. Autenticação central. Aplicação de políticas em nível de ferramenta. Trilha de auditoria completa. Implantável com um único comando Docker — inclusive no Windows, onde o MCP tem 6 modos de falha documentados que a documentação oficial não cobre.

Feito para equipes que já disseram sim ao MCP e agora precisam executá-lo com segurança:

• Controle de tokens — filtre a exposição de ferramentas por cliente para que o inchaço de contexto não cresça com o número de servidores
• Operações prontas para auditoria — cada chamada de ferramenta registrada com chamador, entrada, latência e status de resposta
• Aplicação de políticas — controle quais ferramentas são executadas, para quem e sob quais condições
• Reforçado para Windows — 6 modos de falha documentados resolvidos, nenhum deles presente na documentação oficial do MCP
• Geração de servidores com IA — descreva uma ferramenta em inglês simples, e o FusionAL a constrói e registra
• Opção pronta para você — nós implantamos, governamos e gerenciamos para você

A questão não é se devemos adotar o MCP. É se sua implantação sobreviverá ao contato com sua equipe de segurança.

---

⚡ Início Rápido (5 Minutos)

Pré-requisitos

• Docker Desktop (instalado e em execução)
• Claude Desktop
• Python 3.11+
• Git

Passo 1: Clone e Instale

git clone https://github.com/JRM-FusionAL/FusionAL.git
cd FusionAL

python -m venv venv
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate         # Windows

pip install -r core/requirements.txt

Passo 2: Inicie o FusionAL

cd core
python -m uvicorn main:app --reload --port 8009

Verifique se está em execução:

curl http://localhost:8009/health

Passo 3: Configure o Claude Desktop

Encontre seu arquivo de configuração:

• Windows: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

⚠️ Usuários de Windows: NÃO use %APPDATA% no caminho — o Claude Desktop não expandirá isso. Codifique o caminho completo. Exemplo: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Adicione o FusionAL como um servidor MCP:

{
  "mcpServers": {
    "fusional-gateway": {
      "url": "http://localhost:8009/sse"
    }
  }
}

Passo 4: Reinicie o Claude Desktop e Teste

Saia completamente e reabra o Claude Desktop. Abra um novo chat e tente:

"Gere um servidor MCP em Python que busque o clima atual para uma determinada cidade."

O FusionAL gerará, registrará e executará automaticamente.

---

🐳 Implantação com Docker

Construa e execute o gateway completo no Docker:

docker build -t fusional .
docker run -d -p 8089:8009 --name fusional fusional

Ou com Docker Compose:

docker compose up -d

Gateway disponível em http://localhost:8089.

---

🏗️ Arquitetura

Claude Desktop / Any MCP Client
         │
         ▼  (SSE or Streamable HTTP)
  FusionAL Gateway  (:8009)
         │
   ┌─────┴──────┐
   ▼            ▼
FastAPI      MCP Transport (/mcp)
REST API     ├── execute_code
             ├── generate_and_execute
             └── generate_mcp_project
         │
         ▼
  Docker Sandbox Executor
  (network isolated, memory capped)
         │
         ▼
  MCP Server Registry (JSON)
  ├── business-intelligence-mcp  (:8101)
  ├── api-integration-hub        (:8102)
  └── content-automation-mcp     (:8103)

Ferramentas MCP (via /mcp)

Ferramenta	Descrição
execute_code	Executa Python em um sandbox de subprocesso isolado
generate_and_execute	Prompt em inglês simples → Claude escreve → executa
generate_mcp_project	Descreva um servidor MCP → Claude constrói o projeto completo

API REST

Endpoint	Método	Descrição
/health	GET	Verificação de saúde
/execute	POST	Executa Python (sandbox Docker opcional)
/register	POST	Registra um servidor MCP no registro
/catalog	GET	Lista todos os servidores registrados
/generate	POST	Gera e inicia um novo servidor a partir de um prompt

---

🛠️ Servidores de Demonstração

Esses servidores acompanham o mcp-consulting-kit e são pré-registrados no gateway FusionAL:

Servidor	Porta	Ferramentas
business-intelligence-mcp	8101	Linguagem natural → SQL (PostgreSQL, MySQL, SQLite)
api-integration-hub	8102	Slack, GitHub Issues, consulta de clientes Stripe
content-automation-mcp	8103	Raspagem web, extração de links, parsing de tabelas, feeds RSS

Inicie a pilha completa de demonstração:

cd ../mcp-consulting-kit
docker compose up -d

---

🔒 Modelo de Segurança

Sandbox Docker

Cada execução de código roda com:

• ✅ Isolamento de rede (--network none)
• ✅ Limites de memória (padrão 128 MB, configurável)
• ✅ Limites de processos (máximo de 64 processos)
• ✅ Sistema de arquivos somente leitura (exceto /tmp)
• ✅ Sem escalonamento de privilégios
• ✅ Execução como usuário não-root

Segurança da API (opcional)

Quando mcp-consulting-kit/showcase-servers/common/security.py está presente, o gateway ativa:

• Autenticação por chave de API em /execute, /register, /generate
• Limitação de taxa
• Configuração de CORS

---

🪟 Correções Específicas para Windows

O FusionAL documenta e resolve 6 modos de falha do MCP no Windows não cobertos na documentação oficial:

1. O Silêncio de 60 Segundos — O Claude Desktop expira sem nenhum erro. Causado pela lentidão na inicialização do socket do Docker.
   Leia a correção →

2. A Armadilha do BOM — O Notepad/VS Code injeta uma marca de ordem de byte em configurações JSON, quebrando o MCP silenciosamente.
   Correção: [System.IO.File]::WriteAllText(path, content, New-Object System.Text.UTF8Encoding($false))

3. A Armadilha da Barra Invertida — Separadores de caminho do Windows em claude_desktop_config.json quebram a inicialização silenciosamente.
   Use barras normais ou barras invertidas duplas escapadas.

4. Expansão de %USERPROFILE% — O Claude Desktop NÃO expande variáveis de ambiente em caminhos de configuração. Codifique-os.

5. Falha no pipe nomeado do Docker — O transporte por pipe nomeado do Docker falha no WSL2. Use /var/run/docker.sock.

6. Tempo limite do registro com 8+ servidores — O Claude Desktop atinge um limite de tempo em hardware de baixo custo.
   Limite seu registro a 8 servidores em i5/i7 de 7ª geração ou inferior.

---

🧰 Construindo Seu Próprio Servidor MCP

Usando o Construtor de IA (via Claude Desktop)

Após conectar o FusionAL, peça ao Claude:

"Gere um servidor MCP que consulte nosso banco de dados PostgreSQL usando linguagem natural."

O FusionAL gera o projeto completo, o compila e o registra no gateway automaticamente.

Estrutura Manual do Servidor

my-server/
├── Dockerfile
├── requirements.txt
├── my_server.py       ← FastMCP tools go here
└── .env

Regras Principais

1. Use decoradores @mcp.tool() em funções assíncronas
2. Apenas docstrings de linha única (docstrings multilinha quebram alguns clientes MCP)
3. Retorne strings formatadas de todas as ferramentas
4. Parâmetros padrão para "", não None
5. Registre em sys.stderr
6. Execute como não-root no Docker

from mcp.server.fastmcp import FastMCP
import sys

mcp = FastMCP("my-server")

@mcp.tool()
async def my_tool(query: str = "") -> str:
    """What this tool does in one line."""
    return f"✅ Result for: {query}"

if __name__ == "__main__":
    mcp.run(transport='stdio')

---

📚 Exemplos

Exemplo	Caminho	O que demonstra
Lançador de Dados	examples/dice-roller/	Dados de D&D (8 ferramentas), parsing de notação de dados
API de Clima	examples/weather-api/	Integração com API externa, tratamento de erros
Utilitários de Arquivo	examples/file-utils/	Acesso seguro ao sistema de arquivos, paginação

---

🚀 Consultoria Pronta para Você

Não quer gerenciar sozinho? O FusionAL oferece implantações MCP prontas para você:

Nível	Escopo	Preço
Instalação Inicial	Ambiente único, servidores principais, reforço para Windows	$2.500–$3.500
Instalação Principal	Pilha completa, servidores personalizados, camada de governança, integração da equipe	$5.000–$9.000
Retainer	Operações contínuas, resposta a incidentes, construção de novos servidores	$1.500–$4.000/mês

Agende uma auditoria gratuita de segurança MCP de 15 min →

---

🤝 Contribuições

Contribuições são bem-vindas. Áreas prioritárias:

• Novos servidores de exemplo
• Correções de compatibilidade com Windows
• Melhorias na documentação
• Cobertura de testes

---

📄 Licença

MIT — veja LICENSE

---

🙏 Créditos

• Anthropic — Claude AI + protocolo MCP
• FastAPI — Framework de API
• FastMCP — Framework de servidor MCP
• Docker — Infraestrutura de contêineres

---

Construído por um desenvolvedor autodidata que corrigiu os problemas do MCP que ninguém mais documentou.
🌐 fusional.dev • ⭐ Dê uma estrela no repositório se isso economizou horas para você

---

🙌 Origem e Inspiração

O FusionAL começou com um vídeo do NetworkChuck.

Se você ainda não assistiu "you need to learn MCP RIGHT NOW!!" — assista primeiro. O Chuck explica os fundamentos melhor que ninguém, e o repositório docker-mcp-tutorial dele é o melhor ponto de partida para entender como os servidores MCP funcionam com Docker.

O exemplo do lançador de dados e a estrutura de início rápido neste repositório são adaptados desse tutorial (licenciado sob MIT).

Onde o FusionAL vai além:

O tutorial do Chuck mostra como construir servidores MCP manualmente — edite um modelo de prompt, cole no Claude, implemente o resultado você mesmo.

O FusionAL remove o humano desse ciclo completamente. Em vez de um arquivo de prompt que você copia e cola, generate_mcp_project é uma chamada de ferramenta ao vivo — o Claude descreve o que quer construir, o FusionAL gera, registra e executa. Sem área de transferência. Sem etapas manuais.

Mais importante, o vídeo do Chuck cobre o catálogo MCP do Docker — mais de 300 servidores que você pode ativar com um clique. Esse é o passo um. O FusionAL é o que você precisa quando um CTO pergunta:

"Ótimo — mas como auditamos o que essas ferramentas estão fazendo? Como aplicamos políticas? Como garantimos que isso não vire um incidente de segurança?"

Essa é a lacuna que o FusionAL foi construído para preencher: governança, auditabilidade e controle operacional para equipes que implantam MCP em escala — especialmente no Windows, onde o catálogo sozinho não é suficiente.