Guides

Serveur MCP

Brancher Claude Code, Cursor ou un agent maison sur les outils de Piqline.

Le serveur MCP expose les mêmes outils que l’API, et un outil par agent. Il utilise le transport HTTP « Streamable HTTP », sans session : chaque requête est indépendante. La clé s’envoie comme pour l’API, dans l’en-tête Authorization.

Les serveurs#

Serveur	Adresse	Contenu
Tous les outils	`https://piqline.com/api/mcp`	tous les outils que la clé peut appeler, et `ask_<agent>` pour chaque agent
Un agent	`https://piqline.com/api/mcp/{agent}`	les outils de cet agent, et son `ask_<agent>`

{agent} vaut piqline, facebook, linkedin, upwork ou onboarding. Le serveur d’un seul agent convient aux clients qui limitent le nombre d’outils.

tools/list ne montre que les outils que la clé peut appeler : un outil absent demande un scope que la clé n’a pas. Les outils ask_<agent> demandent le scope agents, et ask_onboarding un rôle owner ou admin.

Brancher un client#

Claude Code#

Shell

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

Cursor et clients qui lisent un fichier mcp.json#

JSON

{
  "mcpServers": {
    "piqline": {
      "url": "https://piqline.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:PIQLINE_API_KEY}" }
    }
  }
}

Clients qui ne parlent qu’à un processus local (stdio)#

mcp-remote relaie un serveur HTTP vers un processus local :

JSON

{
  "mcpServers": {
    "piqline": {
      "command": "npx",
      "args": ["mcp-remote", "https://piqline.com/api/mcp", "--header", "Authorization:${PIQLINE_AUTH}"],
      "env": { "PIQLINE_AUTH": "Bearer piq_live_…" }
    }
  }
}

Les outils ask_<agent>#

ask_piqline, ask_facebook, ask_linkedin, ask_upwork et ask_onboarding confient une demande entière à l’agent correspondant, comme POST/api/v1/agents/{agent}.

Argument	Rôle
`message`	La demande, en langage naturel (obligatoire).
`history`	Les échanges précédents avec cet agent, du plus ancien au plus récent : des objets `{ "role": "user" ou "assistant", "text": "…" }`.

La réponse contient le texte de l’agent. Quand l’agent s’arrête pour une question ou pour une action à confirmer, elle le dit et indique l’outil à appeler.

Annotations#

Chaque outil déclare readOnlyHint, destructiveHint et openWorldHint. Un client peut s’en servir pour demander une confirmation avant les outils qui écrivent, suppriment ou lisent en direct.

Erreurs#

Un outil qui échoue répond avec isError: true et un message lisible. Les refus qui précèdent l’outil (clé, scope, limite) sont des réponses HTTP 401, 403 ou 429 en application/problem+json, décrites dans Erreurs. Les deux cas apparaissent dans l’historique des requêtes de Settings → API and MCP.

Pas encore pris en charge#

Les connecteurs distants qui exigent une connexion OAuth, comme ceux de claude.ai et de ChatGPT, ne peuvent pas encore se brancher : seules les clés sont acceptées.