Servidor MCP · Agent-Lab

Todas as aplicações Agent-Lab incluem um servidor Model Context Protocol construído sobre o FastMCP, montado em /mcp (Streamable HTTP, sem estado). Os clientes MCP — Claude Desktop, IDEs, os 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 os seus registadores de ferramentas/prompts participam no mesmo mecanismo de descoberta que os agentes: scan_packages e o grupo de entry points agent_lab.agents.

O que o servidor expõe

Ferramenta	Descrição
`get_agent_list`	Listar os agentes registados na aplicação em execução
`get_message_list`	Ler o histórico de diálogo de um agente
`post_message`	Enviar uma mensagem a um agente — comunicação entre agentes
`read_prompt_mcp`	Ler um template de prompt; também exposto como prompt MCP (`prompts/get`) e como resource (`prompt://`)

O trio de prompts disponibiliza os prompts de sistema predefinidos de cada tipo de agente, com substituições por tenant através de agent_type + setting_key.

Experimentar com o MCP Inspector

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

npx @modelcontextprotocol/inspector

Aceda à consola web (utilize a ligação do proxy apresentada na consola).

Demonstração do MCP Inspector

Ligar o Claude Desktop

Nota: o Claude Desktop é utilizado aqui apenas para demonstração. Este projeto não tem qualquer afiliação com a Anthropic AI.

Instale a bridge mcp-proxy utilizada pelo Claude Desktop para aceder a servidores HTTP remotos:
```
pip install mcp-proxy
```
Abra Settings → Developer → Edit Config e edite claude_desktop_config.json (adapte o endpoint à sua instalação; o ambiente Python tem de conter mcp-proxy):

Configuração do Claude Desktop 1

Configuração do Claude Desktop 2

Configuração do Claude Desktop 3

Reinicie o Claude Desktop e navegue novamente até Settings → Developer — o Agent-Lab deverá estar visível:

Configuração do Claude Desktop 4

Experimente: peça ao Claude para listar os agentes, obter o histórico de diálogo de uma instância do agente programador supervisionado ou mostrar um excerto de código gerado anteriormente pelo agente:

Demonstração do Claude Desktop

OpenAI Responses API

A ferramenta Model Context Protocol (MCP) alojada na Responses API facilita a ligação a serviços externos: configure o modelo uma única vez para apontar para um servidor MCP — este funciona como um anfitrião centralizado de ferramentas. (Fonte: MCP Tool Guide)

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

Adicionar as suas próprias ferramentas e prompts

Tudo é descoberto da mesma forma que os agentes — basta aplicar o decorator e (no caso de quem consome a biblioteca) garantir que o pacote está em scan_packages ou é publicado através do grupo de entry points agent_lab.agents.

Uma ferramenta — uma simples função async; o parâmetro inicial 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 no trio completo 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, através de @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."])

O scaffold inclui um exemplo completo (mcp/tools.py, mcp/prompts.py) — consulte O seu primeiro agente.

Autenticação

Quando a autenticação está ativada, os clientes MCP autenticam-se através de um proxy OAuth suportado pelo Keycloak: verificação de JWT face ao JWKS do realm (scopes openid, profile, email) e armazenamento de clientes OAuth no Redis (encriptado). A aplicação publica os endpoints de metadados padrão (/.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server/mcp) para que os clientes compatíveis se possam configurar automaticamente.