Server MCP

Ogni applicazione Agent-Lab include un server Model Context Protocol basato su FastMCP, montato su /mcp (Streamable HTTP, stateless). I client MCP (Claude Desktop, IDE, i tuoi agenti) possono individuare gli agenti dell'app, leggere la cronologia dei dialoghi e conversare direttamente con gli agenti. Il server e i suoi registrar di tool/prompt partecipano allo stesso meccanismo di discovery degli agenti: scan_packages e il gruppo di entry point agent_lab.agents.

Cosa espone il server

La tripletta dei prompt rende disponibili i prompt di sistema predefiniti di ogni tipo di agente, con override per tenant tramite agent_type + setting_key.

Provalo con MCP Inspector

Avvia MCP Inspector e connettiti alla tua app (ad es. http://localhost:18000/mcp, transport: Streamable HTTP):

npx @modelcontextprotocol/inspector

Accedi alla console web (usa il link del proxy stampato nella console).

Collegare Claude Desktop

Nota: Claude Desktop viene usato qui solo a scopo dimostrativo. Questo progetto non è affiliato con Anthropic AI.

1. Installa il bridge mcp-proxy usato da Claude Desktop per raggiungere i server HTTP remoti:

   pip install mcp-proxy

2. Apri Settings → Developer → Edit Config e modifica claude_desktop_config.json (adatta l'endpoint alla tua installazione; l'ambiente Python deve contenere mcp-proxy):

3. Riavvia Claude Desktop e torna in Settings → Developer: Agent-Lab dovrebbe essere visibile:

4. Provalo: chiedi a Claude di elencare gli agenti, di recuperare la cronologia dei dialoghi di un'istanza di agente coder supervisionato o di mostrarti uno snippet generato in precedenza dall'agente:

OpenAI Responses API

Il tool Model Context Protocol (MCP) ospitato nella Responses API semplifica la connessione a servizi esterni: configura il modello una sola volta perché punti a un server MCP, che funge da host centralizzato dei tool. (Fonte: MCP Tool Guide)

Un notebook che illustra l'integrazione della OpenAI Responses API con il server MCP di Agent-Lab è disponibile in notebooks/11_mcp_client-openai-responses.ipynb.

Aggiungere tool e prompt personalizzati

Tutto viene individuato allo stesso modo degli agenti: applica il decorator e (se usi la libreria) assicurati che il tuo package sia in scan_packages o pubblicato tramite il gruppo di entry point agent_lab.agents.

Un tool: una semplice funzione async; il parametro iniziale container viene iniettato dal container DI e nascosto ai client:

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}!"

Un prompt: esposto sull'intera tripletta dei prompt (tool / 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."

Avanzato: una sottoclasse completa di McpRegistrar (o PromptSetRegistrar) per insiemi personalizzati di tool/prompt/resource, tramite @discoverable_mcp_registrar(extra_deps=(...)). Per aggiungere istruzioni MCP per i client, passa dei frammenti in fase di composizione:

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

Lo scaffold include un esempio completo (mcp/tools.py, mcp/prompts.py): vedi Il tuo primo agente.

Autenticazione

Quando l'autenticazione è abilitata, i client MCP si autenticano tramite un proxy OAuth basato su Keycloak: verifica dei JWT rispetto al JWKS del realm (scope openid, profile, email) e archiviazione dei client OAuth in Redis (cifrata). L'app pubblica gli endpoint di metadati standard (/.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server/mcp), così i client conformi possono configurarsi in autonomia.