AgentHub MCP Server Runtime

Servidor MCP que expõe as capacidades do AgentHub (Skills, Knowledge Bases, Prompts) via protocolo Model Context Protocol, permitindo que sistemas externos como Claude Desktop, IDEs e outros agentes consumam as capacidades da plataforma.

Visão Geral

Claude Desktop / IDE / Agente externo
        │ (stdio ou HTTP)
        ▼
agenthub-mcp-server-runtime
        │
        ├── GET /api/skills?status=ACTIVE ───► agenthub-backend:8080
        ├── GET /api/knowledge-bases ─────────► agenthub-backend:8080
        └── POST /api/v1/skills/invoke ───────► agenthub-skill-runtime:8082

Capacidades Expostas

| Tipo MCP | Origem AgentHub | Descrição | |----------|----------------|-----------| | Tools | Skills ativas | Cada skill vira uma MCP Tool com seu inputSchema | | Resources | Knowledge Bases | URI: agenthub://kb/{id} | | Prompts | Curados (hardcoded) | Templates para operações comuns |

Prompts disponíveis

• pesquisar-conhecimento — busca semântica em knowledge bases
• executar-skill — executa uma skill com parâmetros JSON

Configuração

Todas as configurações são via variáveis de ambiente:

| Variável | Descrição | Padrão | |----------|-----------|--------| | AGENTHUB_TENANT_ID | Obrigatório. UUID do tenant | — | | AGENTHUB_BACKEND_URL | URL do agenthub-backend | http://agenthub-backend:8080 | | AGENTHUB_SKILL_RUNTIME_URL | URL do agenthub-skill-runtime | http://agenthub-skill-runtime:8082 | | AGENTHUB_API_TOKEN | Bearer token para autenticação | — | | STDIO_MODE | Iniciar em modo stdio | true | | HTTP_PORT | Porta do servidor HTTP (0 = desabilitado) | — |

Modos de Transporte

Modo stdio (padrão — Claude Desktop)

O servidor lê requisições JSON-RPC do stdin e escreve respostas no stdout. Ideal para integração com Claude Desktop, que lança o servidor como subprocesso.

// ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "agenthub": {
      "command": "/caminho/para/mcp-server-runtime",
      "env": {
        "AGENTHUB_TENANT_ID": "seu-tenant-uuid",
        "AGENTHUB_BACKEND_URL": "http://localhost:8080",
        "AGENTHUB_SKILL_RUNTIME_URL": "http://localhost:8082",
        "AGENTHUB_API_TOKEN": "seu-token",
        "STDIO_MODE": "true"
      }
    }
  }
}

Modo HTTP (ambientes containerizados)

Quando HTTP_PORT está definido, o servidor também expõe endpoints HTTP:

# Iniciar em modo HTTP puro
AGENTHUB_TENANT_ID=uuid STDIO_MODE=false HTTP_PORT=8080 ./mcp-server-runtime

# Health check
curl http://localhost:8080/health

# Enviar requisição JSON-RPC
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Exemplos de Uso

Handshake de inicialização

// Requisição
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude","version":"1.0"}}}

// Resposta
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{},"prompts":{}},"serverInfo":{"name":"agenthub-mcp-server-runtime","version":"1.0.0","protocolVersion":"2024-11-05"}}}

Listar tools (skills)

// Requisição
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Resposta
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"document-search","description":"Busca semântica em documentos","inputSchema":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"}},"required":["query"]}}]}}

Invocar uma tool (skill)

// Requisição
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"document-search","arguments":{"query":"arquitetura do AgentHub","limit":5}}}

// Resposta
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"documents\":[...]}"}],"isError":false}}

Listar re

... View full README on GitHub