Per gli sviluppatori

Cosa deve sapere un client sul server, e come chiamarlo senza un assistente in mezzo.

Il protocollo così come lo serviamo

  • Streamable HTTP su https://api.publicwww.com/mcp: un messaggio JSON-RPC per ogni POST (è accettato anche un batch), le risposte sono semplice application/json. Niente server-sent events, niente sessioni: ogni richiesta porta con sé il proprio token. GET restituisce 405.
  • Entrambe le generazioni del protocollo sono servite allo stesso URL: le revisioni con l'handshake initialize (dalla 2024-11-05 alla 2025-11-25) e la 2026-07-28 con server/discover, in cui la versione e le capacità del client viaggiano in params._meta di ogni richiesta e Mcp-Method / Mcp-Name devono corrispondere al corpo.
  • Un token assente o eliminato dà 401 su qualsiasi richiesta, con un header WWW-Authenticate che indica i metadati della risorsa protetta (RFC 9728), da cui un client OAuth trova l'authorization server. Il flusso è in OAuth 2.1 per le applicazioni.
  • Strumenti: search e account, descritti in Strumenti. Niente resources, niente prompts, e l'elenco non cambia tra una chiamata e l'altra.
  • Senza token, la server card descrive il server: nome, indirizzo, versioni del protocollo e link. È elencata in https://publicwww.com/.well-known/ai-catalog.json. L'elenco degli strumenti non fa parte della card; arriva da tools/list una volta che il client ha un token.

Chiamarlo con curl

Il server non conserva alcuno stato tra una chiamata e l'altra, quindi uno strumento si può chiamare subito, senza handshake: 

curl https://api.publicwww.com/mcp \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
          "params":{"name":"search","arguments":{"query":"\"angular.min.js\"","rows":3}}}'

L'elenco degli strumenti con i relativi schemi di input: 

curl https://api.publicwww.com/mcp \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Queste chiamate e una verifica dell'account, in un unico script: mcp-curl.sh.

Per uno script che ha bisogno solo dei risultati di ricerca, la REST API è la strada più semplice: la stessa ricerca e lo stesso token, con CSV, NDJSON e gli altri formati.

Successivo Lingue