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#
| Server | URL | Contenuto |
|---|---|---|
| Tutti i tool | https://piqline.com/api/mcp | ogni tool che la chiave può chiamare, e ask_<agent> per ogni agente |
| Un agente | https://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:
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}.
| Argomento | Ruolo |
|---|---|
message | La richiesta, in linguaggio naturale (obbligatorio). |
history | Gli 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.