ドキュメント · 連携

Add to magpie

ユーザーにリンクを 1 つ渡すだけで、あなたのモデルが彼らの使うすべてのエージェントに現れます：Claude Code、Codex、OpenCode、Gemini CLI、Pi、Crush。設定ファイルも環境変数も、ベース URL のコピー＆ペーストも要りません。

リンクに含まれるホスト、キー、モデルを示し、Acme Relay を追加するか確認する magpie — ユーザーに表示される画面。「追加」を押すまで何も保存されません。

クイックスタート

リンクを作るエンドポイントを URL パラメータで記述します：名前、対応する API ごとのベース URL、必要ならユーザーのキーと提供するモデル。
ボタンに載せるダッシュボードの、発行したばかりのキーの隣に：Add to magpie。
ユーザーが確認するmagpie が開き、プロンプトとキーの送信先を正確に示し、ユーザーが同意するとプロバイダを追加します。すべてのエージェントがすぐに使えます。

リンク

https://usemagpie.ai/import#name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

リンク形式

magpie は magpie:// スキームをシステムに登録します。インポートリンクは、このスキームと import、そしてクエリ文字列でできています：

magpie://import?name=Acme%20Relay&chat=https://api.acme.example/v1&key=sk-…

Web では、代わりに usemagpie.ai/import にリンクし、同じパラメータを # の後ろに置きます：

https://usemagpie.ai/import#name=Acme%20Relay&chat=https://api.acme.example/v1&key=sk-…

https リンクを使う理由

通常のリンクが使える場所ならどこでも機能します。GitHub の README、チャットアプリ、メールクライアントはカスタムスキームを削除したりブロックしたりします。リンクは magpie を開き、まだインストールされていなければダウンロードを案内します。

`#` の後ろに置く理由

ブラウザはフラグメントをサーバーに送りません。キーはあなたのページからユーザーのマシンへ直接渡り、usemagpie.ai を経由せず、ログにも残りません。

値はすべて、URLSearchParams や urlencode が出力する形で URL エンコードします。スペースは %20 と + のどちらでも構いません。

パラメータ

リンクは、ベンダーのエンドポイントをすでに知っている magpie のプリセットを指定するか、名前と少なくとも 1 つのベース URL でプロバイダを一から記述します。

パラメータ	意味
`name`または preset	magpie でのプロバイダの名前。最大 80 文字。
`chat`	OpenAI Chat Completions のベース URL。`/v1` で終わります（magpie が `/chat/completions` を付け足します）。
`responses`	OpenAI Responses のベース URL。`/v1` で終わります。Codex はこの API しか話せません。あなたが対応していない場合は magpie が変換します。
`anthropic`	Anthropic Messages のベース URL：`/v1` を含まないルート。
`key`	ユーザーの API キー。省略すると、ユーザーがダイアログに貼り付けます。
`models`	エージェントに提供するモデル id（カンマ区切り）。省略すると、magpie はあなたの `/v1/models` が返すモデルを一覧にします。
`id`	エージェントが `id/model` で使う id。デフォルトは名前を小文字にしてハイフンでつないだもの（`Acme Relay` → `acme-relay`）。
`catalog`	メタデータを適用する models.dev のプロバイダ id。たとえば OpenAI モデルを中継するサービスなら `openai`。提供されるのは、表示名、コンテキスト長（対応するエージェントに書き込まれます）、推論レベル、画像入力の可否、プロバイダ自身の `/models` が読めないときのモデル一覧、そしてトークンあたりの価格です。価格は使用量ページで USD の概算コストになります。カンマ区切りで複数の id を指定でき、それぞれのモデルがまとめられます。同じモデルが複数にある場合は先に書いたものが使われます。
`website`	あなたのサイト（https）。プロバイダのページに表示されます。
`keys`	ユーザーがキーを作成するページ（https）。リンクにキーがないとき、ダイアログからこのページへリンクします。
`icon`	独自の画像（https）：PNG、JPEG、GIF、WebP、ICO、SVG のいずれかで、最大 1 MB。ユーザーがインポートを確認した後に magpie が一度だけダウンロードし、プロバイダと一緒に保存します。省略すると、magpie は `catalog` のベンダーのロゴか、シンプルなマークを表示します。
`preset`または name	プリセット id。そのエンドポイント、カタログ、ページが使われます。`name` で名前を変えられます。
`region`	リージョンのあるプリセットで、どのリージョンを使うか。

プリセットを使わない場合、chat、responses、anthropic のうち少なくとも 1 つが必要です。対応する API はすべて指定してください。各エージェントはネイティブに話せるものを使います。ベース URL は https でなければなりません。ただし localhost、ループバック、プライベートアドレス、*.local 宛ては、モデルサーバーが通常 TLS なしで動くため、http も使えます。クエリ、フラグメント、認証情報は含められません。

プリセット

magpie が組み込みで知っているベンダーです。magpie presets で最新の一覧を表示できます。

anthropicopenaigoogledeepseekxaimoonshotKimimoonshot-cnkimi-codekimi-code-cnzhipuGLM · api · codingzaiapi · codingminimaxminimax-cnstepfunplan · apistepfun-cnplan · apixiaomiMiMobaidu-qianfan千帆 · personal · team · apitencent-cloudplan · cn · intlhuaweicloudplan · apivolcengine火山方舟 · coding · agent · apiqwenqwen-cnqwen-token-planmistralgroqbedrockollama-cloudopenrouteropencode-goclinepassopencode-zenkilocommandcodetogetherfireworkssiliconflownvidiamodelscope魔搭aihubmixpipellm302aicherryinyylxauto · global · cnollamalmstudio

プリセットのあるベンダーなら、キーを付けるだけです：magpie://import?preset=deepseek&key=sk-…。一覧に追加したい場合は issue を作成してください。

リンクビルダー

エンドポイントを入力すると、リンク、ボタン、Markdown が入力に合わせて生成されます。内容はすべてこのページの中にとどまります。

Web リンク

アプリリンク

HTML

Markdown

試してみるmagpie が開きます。確認するまで何も追加されません。

ボタン

ライトページ用とダークページ用、2 つの既製バッジがあります。インポートリンクにリンクするか、自分でボタンを作ってください。Add to magpie の文言と鳥のマークは自由に使えます。

HTML

<a href="https://usemagpie.ai/import#preset=deepseek&key=sk-…">
  <img src="https://usemagpie.ai/img/add-to-magpie.svg" alt="Add to magpie" width="176" height="40">
</a>

Markdown

[![Add to magpie](https://usemagpie.ai/img/add-to-magpie.svg)](https://usemagpie.ai/import#preset=deepseek)

ダークページには add-to-magpie-light.svg を使ってください。README のような公開ページには決してキーを含めないでください。key を省けば、ユーザーが自分のキーを貼り付けます。

バックエンドで生成

ボタンを置くのに最適なのは、発行したばかりのキーを表示するページです。キーがある場所でリンクを生成します：

JavaScript

const params = new URLSearchParams({
  name: "Acme Relay",
  chat: "https://api.acme.example/v1",
  anthropic: "https://api.acme.example",
  key: apiKey,
  models: ["gpt-5.5", "claude-sonnet-5"].join(","),
  icon: "https://acme.example/logo.svg",
});
const href = "https://usemagpie.ai/import#" + params;

Python

from urllib.parse import urlencode

href = "https://usemagpie.ai/import#" + urlencode({
    "name": "Acme Relay",
    "chat": "https://api.acme.example/v1",
    "anthropic": "https://api.acme.example",
    "key": api_key,
    "models": "gpt-5.5,claude-sonnet-5",
    "icon": "https://acme.example/logo.svg",
})

ターミナル

magpie import 'magpie://import?preset=deepseek&key=sk-…'   # 先に確認します。-y で省略

セキュリティ

インポートリンクは提案にすぎません。決めるのはユーザーです。

必ず確認される。magpie は名前、プロンプトとキーの送信先となるすべてのホスト、モデルを表示し、ユーザーが「追加」を押すまで何も保存しません。ユーザーは先に名前を変えたり、キーを差し替えたりできます。
黙って上書きしない。id がすでに使われている場合、ダイアログがそう伝え、ボタンは置き換えになります。
https のみ。このマシンとローカルネットワーク宛て以外の http は拒否されます。file:、URL 内の認証情報、その他のスキームは即座に拒否されます。
読み込みは一度だけ。アプリ内では、リンクの内容がウィンドウに一度だけ渡されます。再読み込みしてもダイアログは再表示されません。
アイコンは埋め込まず、取得する。icon= の URL は magpie 自身がダウンロードします。ユーザーがインポートを確認した後だけ、https 経由だけ、自身のアイコンフォルダへだけ — 最大 1 MB で、形式もチェックされます。ホストは接続時に名前解決され、ループバック、プライベート、リンクローカル、予約済みアドレスに解決された場合は接続を拒否するため、ユーザー自身のマシンを指す名前（や DNS リバインディング）は拒否されます。ページとダイアログがリモートの画像を直接読み込むことはありません。
キーはサーバーを通らない。Web リンクはパラメータをフラグメントに置きます。キーは最終的に ~/.config/magpie/providers.json にのみ保存され、ユーザー本人しか読めません。

リンク内のキーは機密情報です。キーをリンクに入れるのは、そのユーザー本人しか見られないページだけにし、できれば magpie 用に発行した、取り消し可能なキーを使ってください。共有キーを公開リンクに入れてはいけません。

対応プラットフォーム

システム	`magpie://` の登録方法
macOS	アプリ自身が登録します。magpie.app を「アプリケーション」に置くだけです。
Windows	magpie の初回起動時に、現在のユーザー向けに登録します。
Linux	デスクトップエントリ（`x-scheme-handler/magpie`）で登録します。インストーラが書き込み、初回起動時にも再度書き込みます。
ターミナル	`magpie import <リンク>` が同じ概要を表示し、追加前に確認します。

インポートリンクには magpie 0.1.8 以降が必要です。magpie がすでに起動している場合、リンクはそのインスタンスに渡され、ウィンドウが前面に表示されます。

Add to magpie

https リンクを使う理由

# の後ろに置く理由

プリセット

`#` の後ろに置く理由