# Servidor MCP

> Os servidores MCP do Piqline, suas ferramentas, as ferramentas ask_<agent> e as anotações.

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

O servidor MCP expõe as mesmas ferramentas que a API, mais uma ferramenta por agente. Ele usa o transporte "Streamable HTTP", sem sessões: cada requisição é independente. A chave é enviada como na API, no cabeçalho `Authorization`.

## Os servidores

| Servidor | URL | Conteúdo |
| --- | --- | --- |
| Todas as ferramentas | `https://piqline.com/api/mcp` | todas as ferramentas que a chave pode chamar, e `ask_<agent>` para cada agente |
| Um agente | `https://piqline.com/api/mcp/{agent}` | as ferramentas desse agente e o seu `ask_<agent>` |

`{agent}` é `piqline`, `requete`, `facebook`, `linkedin`, `upwork` ou `onboarding`. O servidor de um único agente serve para os clientes que limitam o número de ferramentas.

`tools/list` mostra apenas as ferramentas que a chave pode chamar: uma ferramenta ausente exige um scope que a chave não tem. As ferramentas `ask_<agent>` exigem o scope `agents`, e `ask_onboarding` o papel de owner ou admin.

## Conectar um cliente

Cada cliente tem o seu bloco para copiar, conferido com a documentação oficial, em [Conecte o seu cliente](/pt/docs/api/clients): Claude, ChatGPT, Codex, Cursor, VS Code, Gemini CLI, Zed, Cline, Mistral Le Chat, Copilot Studio, n8n, LangChain, o Vercel SDK e um relay para qualquer cliente local. Por exemplo, no Claude Code:

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

## As ferramentas ask_<agent>

`ask_piqline`, `ask_requete`, `ask_facebook`, `ask_linkedin`, `ask_upwork` e `ask_onboarding` entregam um pedido inteiro ao agente correspondente, como [`POST /api/v1/agents/{agent}`](/pt/docs/api/agents).

| Argumento | Função |
| --- | --- |
| `message` | O pedido, em linguagem natural (obrigatório). |
| `history` | Trocas anteriores com esse agente, da mais antiga à mais recente: objetos `{ "role": "user" or "assistant", "text": "…" }`. |

A resposta contém o texto do agente. Quando o agente para por causa de uma pergunta ou de uma ação a confirmar, a resposta informa isso e indica a ferramenta a chamar.

## Anotações

Cada ferramenta declara `readOnlyHint`, `destructiveHint` e `openWorldHint`. Um cliente pode usá-las para pedir confirmação antes das ferramentas que escrevem, apagam ou leem ao vivo.

## Erros

Uma ferramenta que falha responde com `isError: true` e uma mensagem legível. As recusas que ocorrem antes da ferramenta (chave, scope, limite) são respostas HTTP `401`, `403` ou `429` em `application/problem+json`, descritas em [Erros](/pt/docs/api/errors). Os dois casos aparecem no histórico de requisições de Configurações → API e MCP.

## Login com a conta

O ChatGPT só aceita login por OAuth ou nenhuma autenticação: hoje ele se conecta à porta aberta, `https://piqline.com/api/open/mcp`. O login com uma conta Piqline (OAuth) está em preparação; todos os outros clientes da página [Conecte o seu cliente](/pt/docs/api/clients) aceitam a chave.
