# Server MCP

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

Source: https://piqline.com/it/docs/api/mcp

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](/it/docs/api/clients): 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:

```bash
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}`](/it/docs/api/agents).

| 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](/it/docs/api/errors). 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](/it/docs/api/clients) accetta la chiave.
