# MCP サーバー

> Piqline の MCP サーバー、そのツール、ask_<agent> ツール、アノテーション。

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

MCP サーバーは、API と同じツールに加えて、エージェントごとに 1 つのツールを公開します。トランスポートは、セッションを使わない「Streamable HTTP」で、各リクエストは独立しています。キーは API と同様に `Authorization` ヘッダーで送ります。

## サーバー一覧

| サーバー | URL | 内容 |
| --- | --- | --- |
| すべてのツール | `https://piqline.com/api/mcp` | キーで呼び出せるすべてのツールと、各エージェントの `ask_<agent>` |
| 1 つのエージェント | `https://piqline.com/api/mcp/{agent}` | そのエージェントのツールと、その `ask_<agent>` |

`{agent}` は `piqline`、`requete`、`facebook`、`linkedin`、`upwork`、`onboarding` のいずれかです。ツール数に上限があるクライアントには、単一エージェントのサーバーが向いています。

`tools/list` に表示されるのは、キーで呼び出せるツールだけです。表示されないツールは、キーにないスコープを必要とします。`ask_<agent>` ツールには `agents` スコープが必要で、`ask_onboarding` にはオーナーまたは管理者のロールが必要です。

## クライアントを接続する

クライアントごとに、公式ドキュメントで確認済みのコピー用ブロックを[クライアントを接続する](/ja/docs/api/clients)に用意しています。対象は Claude、ChatGPT、Codex、Cursor、VS Code、Gemini CLI、Zed、Cline、Mistral Le Chat、Copilot Studio、n8n、LangChain、Vercel SDK と、あらゆるローカルクライアント向けのリレーです。たとえば Claude Code では次のようにします。

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

## ask_<agent> ツール

`ask_piqline`、`ask_requete`、`ask_facebook`、`ask_linkedin`、`ask_upwork`、`ask_onboarding` は、リクエスト全体を対応するエージェントに渡します。[`POST /api/v1/agents/{agent}`](/ja/docs/api/agents)と同じ動作です。

| 引数 | 役割 |
| --- | --- |
| `message` | 自然言語のリクエスト（必須）。 |
| `history` | このエージェントとのこれまでのやり取り。古い順で、`{ "role": "user" または "assistant", "text": "…" }` のオブジェクト。 |

レスポンスにはエージェントのテキストが入ります。質問や確認が必要なアクションのためにエージェントが停止した場合は、その旨と、呼び出すべきツールの名前が示されます。

## アノテーション

各ツールは `readOnlyHint`、`destructiveHint`、`openWorldHint` を宣言します。クライアントはこれらを使って、書き込み、削除、ライブ読み取りを行うツールの前に確認を求められます。

## エラー

失敗したツールは、`isError: true` と読みやすいメッセージを返します。ツールの前段で起きる拒否（キー、スコープ、制限）は、`application/problem+json` の HTTP `401`、`403`、`429` で返され、[エラー](/ja/docs/api/errors)で説明しています。どちらの場合も、設定の API と MCP にあるリクエスト履歴に記録されます。

## アカウントでのサインイン

ChatGPT が受け付けるのは、OAuth サインインか認証なしだけです。現時点では、オープンな入口 `https://piqline.com/api/open/mcp` に接続します。Piqline アカウントでのサインイン（OAuth）は準備中です。[クライアントを接続する](/ja/docs/api/clients)にあるその他のクライアントは、すべてキーを受け付けます。
