Servidor MCP

Toda aplicação Agent-Lab inclui um servidor Model Context Protocol construído com FastMCP, montado em /mcp (Streamable HTTP, stateless). Clientes MCP — Claude Desktop, IDEs, seus próprios agentes — podem descobrir os agentes da aplicação, ler o histórico de diálogos e conversar diretamente com os agentes. O servidor e seus registradores de ferramentas/prompts participam do mesmo mecanismo de descoberta que os agentes: scan_packages e o grupo de entry points agent_lab.agents.

O que o servidor expõe

Essa tríade de prompts disponibiliza os prompts de sistema padrão de cada tipo de agente, com sobrescritas por tenant via agent_type + setting_key.

Experimente com o MCP Inspector

Inicie o MCP Inspector e conecte-se à sua aplicação (por exemplo, http://localhost:18000/mcp, transporte: Streamable HTTP):

npx @modelcontextprotocol/inspector

Acesse o console web (use o link do proxy exibido no console).

Conecte o Claude Desktop

Observação: o Claude Desktop é usado aqui apenas para demonstração. Este projeto não é afiliado à Anthropic AI.

1. Instale a ponte mcp-proxy, usada pelo Claude Desktop para acessar servidores HTTP remotos:

   pip install mcp-proxy

2. Abra Settings → Developer → Edit Config e edite claude_desktop_config.json (adapte o endpoint à sua instalação; o ambiente Python deve conter o mcp-proxy):

3. Reinicie o Claude Desktop e acesse Settings → Developer novamente — o Agent-Lab deve aparecer:

4. Experimente: peça ao Claude para listar os agentes, buscar o histórico de diálogos de uma instância do agente programador supervisionado ou mostrar um trecho de código que o agente gerou anteriormente:

OpenAI Responses API

A ferramenta hospedada de Model Context Protocol (MCP) na Responses API facilita a conexão com serviços externos: configure seu modelo uma única vez para apontar para um servidor MCP — ele atua como um host centralizado de ferramentas. (Fonte: MCP Tool Guide)

Um notebook que demonstra a integração da OpenAI Responses API com o servidor MCP do Agent-Lab está disponível em notebooks/11_mcp_client-openai-responses.ipynb.

Adicione suas próprias ferramentas e prompts

Tudo é descoberto da mesma forma que os agentes — aplique o decorator e (para quem consome a biblioteca) garanta que seu pacote esteja em scan_packages ou publicado pelo grupo de entry points agent_lab.agents.

Uma ferramenta — uma função async simples; seu primeiro parâmetro, container, é injetado a partir do container de DI e fica oculto para os clientes:

from agent_lab import discoverable_mcp_tool


@discoverable_mcp_tool(
    "my_hello_tool",
    description="Returns a friendly greeting.",
    annotations={"readOnlyHint": True},
)
async def hello_tool(container, name: str) -> str:
    return f"Hello, {name}!"

Um prompt — exposto em toda a tríade de prompts (ferramenta / prompts/get / resource prompt://):

from agent_lab import discoverable_mcp_prompt


@discoverable_mcp_prompt("my_greeting_prompt")
def greeting_prompt() -> str:
    return "Greet the user warmly and briefly."

Avançado — uma subclasse completa de McpRegistrar (ou PromptSetRegistrar) para conjuntos personalizados de ferramentas/prompts/resources, via @discoverable_mcp_registrar(extra_deps=(...)). Para adicionar instruções MCP para os clientes, passe fragmentos na composição:

app = create_app(mcp_instructions=["Extra guidance for MCP clients."])

Um exemplo completo acompanha o scaffold (mcp/tools.py, mcp/prompts.py) — consulte Seu primeiro agente.

Autenticação

Quando a autenticação está ativada, os clientes MCP se autenticam por meio de um proxy OAuth apoiado no Keycloak: verificação de JWT contra o JWKS do realm (escopos openid, profile, email) e armazenamento dos clients OAuth no Redis (criptografado). A aplicação publica os endpoints de metadados padrão (/.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server/mcp) para que clientes compatíveis possam se autoconfigurar.