使用说明

AgentHub MCP Client Runtime (Go)

MCP Client Runtime - Cliente Go para conectar em servidores MCP externos e expor via gRPC para o backend Java.

📋 Visão Geral

O MCP Client Runtime permite que o AgentHub se conecte a servidores Model Context Protocol (MCP) externos, descobrindo e executando suas capabilities (tools, prompts, resources).

🏗️ Arquitetura

┌────────────────────────────────────────────────────────────┐
│                  AgentHub Platform                          │
├────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────┐         ┌──────────────────┐           │
│  │  Skill Runtime │────────>│  MCP Client      │           │
│  │  (Java)        │  gRPC   │  Runtime (Go)    │           │
│  │                │         │                  │           │
│  │  - Tools       │         │  - MCP Protocol  │           │
│  │  - Skills      │         │  - Stdio Client  │           │
│  └────────────────┘         │  - gRPC Server   │           │
│                              └────────┬─────────┘           │
│                                       │                     │
│                                       │ stdio               │
│                                       │                     │
│                              ┌────────v─────────┐           │
│                              │  External MCP    │           │
│                              │  Servers         │           │
│                              │                  │           │
│                              │  - filesystem    │           │
│                              │  - github        │           │
│                              │  - slack         │           │
│                              │  - custom...     │           │
│                              └──────────────────┘           │
│                                                              │
└────────────────────────────────────────────────────────────┘

🚀 Funcionalidades

1. MCP Client (stdio transport)

✅ Conectar a servidores MCP via stdio (subprocess)
✅ Implementar protocolo JSON-RPC 2.0
✅ Gerenciar lifecycle de processos (spawn, kill, restart)
✅ Handle input/output streams

2. Discovery

✅ Listar tools disponíveis no servidor MCP
✅ Listar prompts disponíveis
✅ Listar resources disponíveis
✅ Schema validation (JSON Schema)

3. Execution

✅ Executar tools com parâmetros
✅ Executar prompts com variáveis
✅ Ler resources
✅ Streaming support (se aplicável)

4. gRPC Bridge

✅ Expor API gRPC para Java backend
✅ Conversão de tipos Go ↔ Protobuf
✅ Error handling e retries
✅ Connection pooling

📦 Estrutura do Projeto

agenthub-mcp-client-runtime/
├── cmd/
│   └── server/
│       └── main.go              # Entry point da aplicação
├── internal/
│   ├── mcp/
│   │   ├── client.go            # MCP client (stdio transport)
│   │   ├── protocol.go          # JSON-RPC 2.0 protocol
│   │   └── types.go             # MCP types (Tool, Prompt, Resource)
│   ├── grpc/
│   │   ├── server.go            # gRPC server implementation
│   │   └── handler.go           # gRPC request handlers
│   └── api/
│       └── http.go              # HTTP API (health check, discovery)
├── pkg/
│   └── mcpclient/
│       └── client.go            # Public client interface
├── proto/
│   └── mcpclient.proto          # Protobuf definitions
├── go.mod
├── go.sum
├── Dockerfile
├── Makefile
└── README.md

🔧 Tecnologias

Go 1.24+ - Linguagem principal
JSON-RPC 2.0 - Protocolo MCP
Gin - HTTP server (health checks)

📝 APIs

HTTP API interna

GET /health - Health check
GET /api/tools - Ponte interna: lista tools MCP agregadas
POST /api/tools/call - Ponte interna: executa uma tool MCP agregada

As rotas de gestão em /servers ficam desabilitadas por padrão. O modo seguro mantém MCP_RUNTIME_ENABLE_MANAGEMENT_API=false; quando uma operação interna controlada exigir gestão, ela deve habilitá-las explicitamente e usar uma identidade de workload validada. Não existe token de gestão por header nem exposição dessas rotas por proxy público.

🚀 Quick Start

Compilar

make build

Executar

./bin/mcp-client-runtime

Configuração multi-tenant

O runtime aceita múltiplos tenants no mesmo pod via AGENTHUB_TENANT_IDS:

AGENTHUB_TENANT_IDS=core,test,acme

AGENTHUB_TENANT_ID continua suportado para bootstrap de configurações e migrations legadas. Ele não seleciona o tenant nas rotas HTTP de execução: /api/tools e /api/tools/call derivam o tenant somente do iss de um token de workload Keycloak validado e rejeitam X-Tenant-ID e tenantId externos.

Docker

O compose padrão não publica portas no host: o runtime permanece acessível somente pela rede Docker interna agenthub-shared-net. Para iniciá-lo nesse perfil, use:

docker compose up --build

Para experimentos locais que precisem expor uma porta, crie um override fora do controle de versão. Esse override não é um perfil de publicação e não deve ser usado com credenciais, tenants ou dados reais.

🔌 Integração interna

A API do AgentHub consome o runtime pela ponte HTTP autenticada de workload. O transporte gRPC legado não possui contrato de autenticação implementado e é recusado por MCP_RUNTIME_ENABLE_GRPC=true; ele não deve ser usado por clientes ou serviços internos.

📚 Servidores MCP Suportados

Oficiais

@modelcontextprotocol/server-filesystem - Operações de filesystem
@modelcontextprotocol/server-github - GitHub API
@modelcontextprotocol/server-git - Git operations
@modelcontextprotocol/server-slack - Slack integration

Custom

Qualquer servidor que implemente MCP protocol via stdio

🔐 Segurança

✅ Validação de inputs (JSON Schema)
✅ Sandboxing de processos
✅ Timeouts configuráveis
✅ Rate limiting
✅ Resource limits (CPU, memory)

📊 Observabilidade

✅ Structured logging (JSON)
✅ OpenTelemetry traces
✅ Prometheus metrics
✅ Health checks

🧪 Testes

make test

📖 Documentação Adicional

MIT License