MCP リファレンス
MCP のエンドポイントは公開 API と同じコードを通ります。Claude が焼いた PDF と
curl が焼いた PDF は同じ関数を通るので、上限・スコープ・公開バージョンの解決が
経路によって食い違うことはありません。
POST https://composepdf.com/mcpトランスポートは Streamable HTTP のステートレスです(Mcp-Session-Id は発行も要求も
しません)。クライアント側の設定は接続ガイドにあります。
| ヘッダー | ログの keyId |
組織 | |
|---|---|---|---|
| API キー | x-api-key / Authorization: Bearer rsp_… |
その鍵 | 鍵が名指す1つ |
| OAuth | Authorization: Bearer <アクセストークン> |
null — 承認したのは人 |
最も古い所属、または organizationId |
資格情報の無いリクエストには 401 と、/.well-known/oauth-protected-resource を指す
WWW-Authenticate ヘッダーを返します。このヘッダーが OAuth 発見の仕組みそのもので、
URL しか受け取らないクライアントはこれを辿って登録まで進みます。
tools/list に出るのは、その資格情報で実際にできることだけです。 render キーに
put_dataset_rows は見えず、data-write キーに render_document は見えません。
見えないツールを試して断られる、という往復が起きないようにしています。
| ツール | ロール | 何をするか |
|---|---|---|
list_documents |
render | 公開済みテンプレートを id⇥タイトル で1行ずつ |
describe_document |
render | そのテンプレートが取る欄を1行ずつ |
open_form |
render | 会話の中に、人が埋めるフォームを出す |
render_document |
render | PDF にして数日保管し、リンクを返す |
put_dataset_rows |
data-write | データセットの配列1本を差し替える |
check_document |
OAuth | 帳票DSL の原本を品質ゲートにかける |
create_document |
OAuth | 通った原本をテンプレートにして公開する |
list_organizations |
OAuth | 所属が2つ以上あるときだけ |
テンプレートを作るのは人であって、鍵ではありません。 check_document と
create_document が出るのは OAuth の接続 — 署名した本人が承認したもの — だけです。
APIキーの2つのロールはどちらも届かないので、誰かの表計算の隅に貼られた鍵は、
テンプレートを焼けてもテンプレートを書けません。
list_documents
Section titled “list_documents”引数はありません。1行につき id・タブ・タイトルを返します。
describe_document
Section titled “describe_document”| 引数 | ||
|---|---|---|
document |
必須 | テンプレートの id または完全なタイトル |
organizationId |
任意 | 所属が2つ以上ある OAuth の呼び手 |
1行につき パス⇥型⇥必須⇥例 を返します。配列の要素はエンジンが報告するのと同じ書き方
(items[].price)なので、エラーに出たパスをそのままここで探せます。
たいていは呼ぶ必要がありません — payload が違えば同じ表がエラーとして返るからです。
読むのは、何かを埋める前にパスが要るとき(たとえば open_form の前)です。
open_form
Section titled “open_form”| 引数 | ||
|---|---|---|
document |
必須 | テンプレートの id または完全なタイトル |
data |
任意 | 会話で既に分かっている値。render_document の data と同じ形で、部分でよい |
organizationId |
任意 | 所属が2つ以上ある OAuth の呼び手 |
MCP Apps を描けるクライアントでは、会話の中に
フォーム(ui://composepdf/document-form)が出ます。埋めて送るとその接続のまま
render_document が走るので、鍵やトークンが増えることはありません。欄は契約の宣言から
出ます — 埋め込みやモバイルと同じ buildForm なので、1つのテンプレートからはどの面でも
同じ欄が出ます。
1つのテンプレートにつき1回だけ呼んでください。 MCP Apps は UI をツールに結び付ける
仕様なので、呼んだ数だけフォームが描かれます。欄のパスを調べるのが describe_document の
仕事で、このツールの仕事ではないのはそのためです。
render_document
Section titled “render_document”| 引数 | ||
|---|---|---|
document |
必須 | テンプレートの id または完全なタイトル |
data |
任意 | 差し込む値。省略するとテンプレート自身のデータセットを使う |
dataList |
任意 | レコードごとに1組、まとめて1つの PDF に綴じる。data と排他 |
fileName |
任意 | 既定はテンプレートのタイトル |
organizationId |
任意 | 所属が2つ以上ある OAuth の呼び手 |
焼くのは常に公開バージョンです。古い版の名指しはレンダリング APIと スタジオの仕事です。
返るのは PDF ではなくリンクです — PDF はメガバイト単位で、ツールの返り値は文脈だからです。
どちらのリンクが出るかは資格情報によります。OAuth の呼び手は API キーを持たないので
ブラウザ用の URL、鍵の呼び手はスタジオのセッションがあるとは限らないので curl の行です。
保管された PDF は保持期間を過ぎると消えます。
check_document
Section titled “check_document”| 引数 | ||
|---|---|---|
source |
必須 | .rpt の中身そのもの(パスではありません) |
data |
任意 | 実データ。省略すると宣言が持つ例の値で組みます |
profiles |
任意 | 業務プロファイル。例: ["invoice-jp"] |
organizationId |
任意 | 所属が2つ以上ある OAuth の呼び手 |
三層のゲートを1回で走らせます — 枠に入らなかった中身、幾何(重なり・版面外・
余白の不揃い・字の大きさが何種類あるか)、そしてプロファイルを指定すれば
「日本の様式として何が書かれていなければならないか」。返るのは1行1件の
行:桁⇥重さ⇥コード⇥本文で、その下に試すべき直し方が付きます。
テンプレートはこうやって直します。 診断を見て直すと収束しますが、ページの絵を 見て直すのは収束しません — 絵は「どこかがおかしい」と言うだけで、「どの行が おかしくしたか」を言わないからです。
このツールの説明文には、実際に通るテンプレート1枚と、つまずきやすい4つの規則が そのまま入っています。下の手本はリソースとしても配っていますが、取得できない クライアントではモデルが構文を推測しはじめ、推測された構文は「何も載っていない ページ」にコンパイルされてしまうためです。説明文は必ず届きます。
create_document
Section titled “create_document”| 引数 | ||
|---|---|---|
title |
必須 | テンプレートの名前 |
source |
必須 | .rpt の中身そのもの |
data |
任意 | レイアウトを検査する実データ |
profiles |
任意 | 業務プロファイル |
organizationId |
任意 | 所属が2つ以上ある OAuth の呼び手 |
原本をコンパイルして公開し、render_document が取る id を返します。
診断にエラーが1件でもある間は断りますが、断り方が診断を連れてくるので、
次の一手で直せます。警告では止まりません — 帳票は何回かに分けて書くもので、
書きかけの下書きを落とすゲートは、使う人が切ってしまうゲートです。
テンプレートは新しいワークスペースに1枚だけ置かれ、.rpt は公開した文書の隣に
「これが元になった原本だ」として残ります。
put_dataset_rows
Section titled “put_dataset_rows”| 引数 | ||
|---|---|---|
datasetId |
必須 | |
path |
必須 | 1区切りだけ。"items" は可、"a.b[0].c" は不可 |
rows |
必須 |
追記ではなく配列まるごとの差し替えです。残したい行はすべて送ってください。 外部データに繋がっているデータセットは、次の読み込みで黙って上書きされる代わりに 書き込みを拒否します。
手本の .rpt を4本、リソースとして配っています — rpt://examples/invoice、
rpt://examples/invoice-qualified、rpt://examples/inspection-report、
rpt://examples/production-schedule。写しではなくリポジトリの実物なので、古くなる
ことがありません。白紙から書き始めるのではなく、いちばん近いものから始めてください。
出るのは、作れる接続と同じところです。
エラーは HTTP のステータスとコードを持ったまま返るので、「今月の枠を使い切った」と 「payload が違う」を区別できます。
400 data_contract_violation |
契約を満たしていない。違反したパスと欄の表を本文が返すので、次の一手で直せる |
402 quota_exceeded |
今月の枠を使い切った、またはプランに API が含まれない |
404 not_found |
一致するテンプレートが無い、または曖昧 — 本文が候補を並べる |
429 rate_limited |
プランの毎分上限を超えた |
変数宣言を持たないテンプレートは契約と照合されません(宣言が生まれる前に公開された
テンプレートも動き続けるため)。その場合は渡されたまま焼けるので、先に
describe_document を読んでください。
document がタイトルを取るのは、人がそう呼ぶからです。完全一致が優先され、2つに当たる
前方一致は推測せず候補を並べて断ります。違うテンプレートを焼くのは、聞き返すより
悪いからです。