AI エージェントから BrewMyPDF を使う（MCP）

BrewMyPDF は Model Context Protocol を話します。エージェントはお客様のテンプレートを見つけ、それぞれがどんなデータを求めるかを知り、PDF を生成できます — お客様の API キー、お客様のクォータ、お客様の監査記録のもとで。

これは何か

BrewMyPDF は MCP サーバーです。つなぎのコードを書かなくても、AI エージェントがテンプレートを一覧し、生成できます。REST API と同じアカウント、同じ API キー、同じクォータ、同じ監査記録です — エージェントが別の身元になることはありません。

サーバーはステートレスです。1 回の HTTP POST が JSON-RPC 2.0 のメッセージ 1 通を運びます。開くセッションも、生かし続けるものもないので、接続が切れても失うものはありません。

つなぐ

お使いの MCP クライアントを https://brewmypdf.com/mcp に向け、API キーを Authorization ヘッダーにベアラートークンとして送ってください。このヘッダーは、x-api-key を使う REST API とは異なりますのでご注意ください — キー自体は同じもので、コンソールの「API キー」で発行します。

mcp.json

{
  "mcpServers": {
    "brewmypdf": {
      "url": "https://brewmypdf.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

キーが誤っている、またはない場合は unauthorized だけを返します。WWW-Authenticate のチャレンジは送りません。こちらが動かしていない探索の流れを広告すると、クライアントを行き止まりの道へ送ることになるからです。unauthorized が返ったら、まずヘッダー名をご確認ください。

tools/list

curl -X POST https://brewmypdf.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

API キーは Professional プランから使えるため、それより下のプランではエージェントをつなげません。

4 つのツール

どのツールも、すでに保存済みのテンプレートに対して働きます。テンプレートを作ったり編集したりするものはありません — 下の「できないこと」をご覧ください。

`list_templates`	List the PDF templates on this account. Returns id, name and last-updated time. Call this first — every other tool needs a template_id from here.
`describe_template_schema`	Describe the JSON data a template expects. Returns a JSON Schema plus the flat list of binding paths found in the template. Types are intentionally left open — the template only says which values it uses, not what they must be. Call this before preview_template or render_pdf.
`preview_template`	Render a template with data to HTML, without producing a PDF. Free and fast — use it to check your data fits before calling render_pdf. Returns the HTML and any binding warnings (a warning is not a failure: it tells you which value was missing or wrong).
`render_pdf`	Render a template with data to a PDF and return a download URL. This consumes one render from the account quota, so preview_template first. If the render takes longer than the wait window you get a job_id with status "queued" instead of a URL.

呼ぶ順序

list_templates で id が分かります。describe_template_schema は id を、そのテンプレートが求める正確な JSON の形に変えます。バインディングのパスもすべて含まれるので、項目名を推測せず、データを送る前にこれを呼んでください。preview_template は無料で HTML を生成するので、データが合っているか確かめられます。そのうえで render_pdf がレンダーを 1 件消費し、署名付きのダウンロード URL を返します。

生成が待ち時間を超えた場合は、URL の代わりに status が queued のジョブ ID が返ります。これは失敗ではありません — ジョブは動いており、同じジョブ ID は REST API でもそのまま使えます。

サーバーはこの順序を、initialize 応答の instructions 項目でモデル自身にも伝えます。クライアントがその文をシステムプロンプトに入れることがあるので、行儀のよいエージェントは何かを呼ぶ前に順序を知っています。

できないこと

テンプレートの作成と編集はできません。テンプレートはウェブのエディタか、REST API（POST /v1/templates と PUT /v1/templates/{id}）で作ります。エージェントに使えるテンプレートがない場合は、まず人が 1 つ作る必要があります。

生成できるのは PDF だけです。PNG や JPEG、そして webhook・バッチ・PDF 操作など、それ以外はすべて REST API をお使いください。

これらのツールは言語モデルを呼びません。説明文からテンプレートを生成する機能はコンソールにある別の機能で、クレジットで計量されます。

2 種類の失敗

ツールが動いたうえで失敗した場合は、isError とメッセージが返ります — テンプレートがない、値が誤っている、クォータを使い切った、などです。内容を読み、入力を直してもう一度お試しください。

JSON-RPC のエラーは、呼び出しがそもそも始まらなかったという意味です: ツール名が違う、必須の引数が抜けている、などです。値を変えて再試行しても解決しません。ツールの一覧を読み直してください。