Vai al contenuto

Guide

Server MCP

I server MCP di Piqline, i loro tool, i tool ask_<agent> e le annotazioni.

Il server MCP espone gli stessi tool dell'API, più un tool per ogni agente. Usa il trasporto «Streamable HTTP», senza sessioni: ogni richiesta è autonoma. La chiave si invia come per l'API, nell'header Authorization.

I server#

ServerURLContenuto
Tutti i toolhttps://piqline.com/api/mcpogni tool che la chiave può chiamare, e ask_<agent> per ogni agente
Un agentehttps://piqline.com/api/mcp/{agent}i tool di quell'agente e il suo ask_<agent>

{agent} è piqline, requete, facebook, linkedin, upwork oppure onboarding. Il server di un solo agente è adatto ai client che limitano il numero di tool.

tools/list mostra solo i tool che la chiave può chiamare: un tool mancante richiede uno scope che la chiave non ha. I tool ask_<agent> richiedono lo scope agents, e ask_onboarding il ruolo owner o admin.

Collegare un client#

Ogni client ha il suo blocco da copiare, verificato sulla documentazione ufficiale, in Collega il tuo client: Claude, ChatGPT, Codex, Cursor, VS Code, Gemini CLI, Zed, Cline, Mistral Le Chat, Copilot Studio, n8n, LangChain, l'SDK Vercel e un relay per qualsiasi client locale. Per esempio, in Claude Code:

Shell
claude mcp add --transport http piqline https://piqline.com/api/mcp \
  --header "Authorization: Bearer $PIQLINE_API_KEY"

I tool ask_<agent>#

ask_piqline, ask_requete, ask_facebook, ask_linkedin, ask_upwork e ask_onboarding affidano un'intera richiesta all'agente corrispondente, come POST/api/v1/agents/{agent}.

ArgomentoRuolo
messageLa richiesta, in linguaggio naturale (obbligatorio).
historyGli scambi precedenti con questo agente, dal più vecchio: oggetti { "role": "user" or "assistant", "text": "…" }.

La risposta contiene il testo dell'agente. Quando l'agente si ferma per una domanda o per un'azione da confermare, la risposta lo indica e nomina il tool da chiamare.

Annotazioni#

Ogni tool dichiara readOnlyHint, destructiveHint e openWorldHint. Un client può usarle per chiedere conferma prima dei tool che scrivono, eliminano o leggono in diretta.

Errori#

Un tool che fallisce risponde con isError: true e un messaggio leggibile. I rifiuti che arrivano prima del tool (chiave, scope, limite) sono risposte HTTP 401, 403 o 429 in application/problem+json, descritte in Errori. Entrambi i casi compaiono nella cronologia delle richieste di Impostazioni → API e MCP.

Accesso con account#

ChatGPT accetta solo l'accesso OAuth o l'assenza di autenticazione: oggi si collega alla porta aperta, https://piqline.com/api/open/mcp. L'accesso con un account Piqline (OAuth) è in preparazione; ogni altro client della pagina Collega il tuo client accetta la chiave.

Una domanda sull'API, o un errore in questa pagina? Scrivici.