ScrapelessをカスタムGPTアクションでChatGPTに接続する方法

TL;DR:

• ChatGPTは、コネクタとしてAPIキーMCPサーバーを受け入れることができません。開発者モードのMCPはOAuth 2.1または認証なしを受け入れ、OpenAIの独自のドキュメントにはChatGPTが「カスタムAPIキーを提示することはできない」と記載されています。
• 機能するルートはカスタムGPT アクションです：OpenAPIスキーマとカスタムヘッダーのAPIキー認証。
• ヘッダーはx-api-tokenであり、Authorization: Bearerではありません。認証タイプをAPIキーに設定し、次にカスタム、そしてそのヘッダー名を設定します。
• HTMLではなくMarkdownを求めてください。同じページはMarkdownとして8,676文字、HTMLとして50,403文字です — マークアップにモデルが使用する文脈で83％の削減です。
• response_typeはjs_render: trueと一緒にのみ機能します。js_renderを除外すると、同じリクエストはHTTP 200で50,368文字のHTMLを返します。outputFormatは受け入れられ、静かに無視され、50,403文字のHTMLが返されます。
• 以下のスキーマはopenapi-spec-validatorをOpenAPI 3.1.0に対して通過させ、説明されているリクエストはライブで実行されました：{code: 200, data: string}。
• 開始する前に、Scrapeless無料プランでキーを取得してください。

ChatGPTに見たことのないページについて尋ねると、トレーニングデータの概要または制御できないブラウジング結果が得られます。アクションは配置を変更します：モデルに対して、定義したパラメータで選択したAPIに対するHTTP操作を1つ渡します。

最初に解決すべきことは、ChatGPTが実際に受け入れるメカニズムが何であるかです。明白な答えは誤りです。

これはアクションであり、MCPコネクタではない理由

他のすべての主要クライアントは、Scrapeless MCPサーバーをリモートHTTPコネクタとして、ヘッダーのキーと共に使用します。ChatGPTはそうではなく、周囲に構築する前にその理由を見ておく価値があります。

エンドポイントには静的ヘッダーが必要です。ヘッダーなしで呼び出されると：

POST https://api.scrapeless.com/mcp   (no auth)
-> HTTP 401
   body: Unauthorized: Missing x-api-token header
   www-authenticate: None

その欠落しているwww-authenticateヘッダーは重要です。HTTP認証フレームワークの下では、401はサーバーが認証方法をアドバタイズする場所であり、OAuthのチャレンジを求めるクライアントは従うべきものが何も見つけられません。また、OAuthメタデータを発見することもありません：

/.well-known/oauth-protected-resource       404
/.well-known/oauth-authorization-server     404
/.well-known/oauth-protected-resource/mcp   404

モデルコンテキストプロトコル仕様では、いずれの配置も許可されています — ヘッダーの生のトークンは完全に普通のMCP展開です。制約はChatGPT側にあります：その開発者モードのコネクタはOAuth 2.1または認証なしをサポートしており、OpenAIのドキュメントは明確にChatGPTがカスタムAPIキーを提示できないことを述べています。

したがって、貼り付けるURLはありません。キー付きHTTP APIのサポートパスはGPTアクションであり、これは選択したヘッダー名のAPIキー認証をサポートしています。

前提条件

• GPTを作成するためのChatGPTプラン。
• Scrapeless APIキー。
• ホスティングなし、プロキシなし、ローカルプロセスなし。アクションはapi.scrapeless.comを直接呼び出します。

ステップ1: OpenAPIスキーマ

アクションは1つ以上の操作を説明するOpenAPIドキュメントです。このアクションは単一の操作を説明します：レンダリングされたページを取得し、Markdownとして返すことです。

openapi: 3.1.0
info:
  title: Scrapeless Universal Scraping API
  description: Fetch a fully rendered web page and return it as Markdown or HTML.
  version: "1.0.0"
servers:
  - url: https://api.scrapeless.com
paths:
  /api/v2/unlocker/request:
    post:
      operationId: scrapeWebPage
      summary: Fetch a web page with JavaScript rendering and return it as Markdown
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [actor, input]
              properties:
                actor:
                  type: string
                  enum: [unlocker.webunlocker]
                  description: The Scrapeless actor to run.
                input:
                  type: object
                  required: [url, js_render, response_type]
                  properties:
                    url:
                      type: string
                      format: uri
                      description: The page to fetch.
                    js_render:
                      type: boolean
                      enum: [true]
                      default: true
                      description: Must be true. response_type only takes effect when JavaScript rendering is on.
                    response_type:
                      type: string
                      enum: [markdown, html]
                      default: markdown
                      description: Return the page as Markdown or raw HTML.
      responses:
        "200":
          description: The rendered page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  data:
                    type: string
                    description: The rendered page, as Markdown or HTML.
        "401":
          description: Missing or invalid API token.
components:
  securitySchemes:
    scrapelessApiKey:
      type: apiKey
      in: header
      name: x-api-token
security:
  - scrapelessApiKey: []

そこには3つの意図的な選択があります。

actorは1つの値を持つenumであり、自由な文字列ではありません。自由なテキストフィールドを与えられたモデルは最終的に俳優名を考案します；enumは唯一の有効な値を唯一の選択肢とします。

operationIdはscrapeWebPageであり、それはGPTの指示で参照される名前です。漠然としたIDは漠然としたツール選択を生じます。

response_typeはmarkdownにデフォルト設定されており、ステップ3の理由から、双方は必須としてリストされています。スキーマフローのデフォルトはドキュメントです：それはモデルにフィールドを送信させるものではなく、API自身のjs_renderのデフォルトはオフです。

貼り付ける前に検証することは30秒の価値があります — OpenAPI 3.1.0仕様は構造について厳格であり、ビルダーのエラーメッセージは簡潔です：

pip install openapi-spec-validator

python3 -c "
from openapi_spec_validator import validate
from openapi_spec_validator.readers import read_from_filename
spec, _ = read_from_filename('scrapeless-action.yaml')
validate(spec)
print('valid')"

valid

ステップ2: 認証

GPTビルダーで、アクションの認証パネルを開き、次のように設定します：

APIキーのデフォルトはBearerで、Authorization: Bearer <key>を送信します。Scrapelessはx-api-tokenのみを読み取り、それ以外は読み取らないため、デフォルトのままだと401が発生し、ビルダーはアクションが最初に呼び出されるときにのみ表示されます — スキーマの検証がすでに完了した後です。

注: ビルダーはウェブUIなので、このステップはこの記事の検証の一部として実行されませんでした。API自体に関するすべての主張 — スキーマ、ヘッダー名、レスポンスの形状、そして以下のサイズ — は、api.scrapeless.comに対するライブコールから得たものです。

ステップ3: Markdownを要求する

この設定は、コネクタが何かを読む前にモデルのコンテキストにどれだけの時間を費やすかを決定し、その違いは測定可能です。

同じカテゴリページを2回取得しました:

response_type=markdown      8,676 chars
default (html)             50,403 chars

Markdownは83%小さいです。GPTアクションのレスポンスはモデルのコンテキストに入るため、HTMLを返すことは、その予算のほとんどをタグやインラインスクリプト、モデルが無視する属性に費やします。

その隣には罠があります。outputFormatは機能するはずであり、異議なく受け入れられます:

input.response_type = "markdown"   ->  8,676 chars  (markdown)
input.outputFormat  = "markdown"   -> 50,403 chars  (HTML)

2回目の呼び出しは成功し、HTTP 200を返し、outputFormatはアクターが読み取るパラメータではないため、静かにHTMLを返しました。拒否されるのではなく無視される未知のキーは、より厄介なバグの一種です — 何も失敗せず、出力は単に形が間違っており、あなたが予算を組んだ量の約6倍の大きさになります。

2つ目の罠は静かです。response_typeはJavaScriptレンダリングがオンのときのみ有効になり、APIのデフォルトはオフです。response_type: "markdown"をjs_render: trueなしで送信すると、呼び出しはHTTP 200を返し、50,368文字のHTMLが返され、エラーも警告もありません。上記のスキーマはjs_renderをtrueに固定し、この理由のためにそれが必須であることを列挙しており、以下の指示では両方のフィールドを指定しています。

これを今構築していますか？ Scrapelessの無料プランは、アクションをエンドツーエンドでテストするのに十分なリクエストをカバーします。

ステップ4: それを呼び出す指示

スキーマはモデルに機能を付与します; 指示はそれがいつ手を伸ばすかを決定します。操作を明示的に名付けましょう:

When the user gives you a URL, or asks about the current contents of a
specific page, call scrapeWebPage with that URL, js_render true and
response_type "markdown". Do not answer from memory when a URL is present.

Return what the page says, and quote the exact figures it contains rather
than paraphrasing them. If scrapeWebPage reports a 401, tell the user the
API key is missing or misconfigured and stop.

最初の段落はツールをトリガーに結びつけます。これがなければ、自身にブラウジングの能力を持つモデルがその代わりに使う場合があり、結果はあなたのスキーマには関与しません。

返ってくるもの

レスポンスエンベロープは2つのフィールドであり、上記のスキーマは両方を宣言しています:

{
  "code": 200,
  "data": "-   [Home](https://books.toscrape.com/index.html)\n-   [Books](...)\n..."
}

スキーマが記述するボディでライブAPIに対して確認されました:

HTTP 200
response keys      : ['code', 'data']
code               : 200 (int)
data               : str, 50403 chars
schema match       : code=integer:True  data=string:True

codeはScrapeless自身のステータスであり、HTTPステータスとは異なります — ここでは両方とも200でした。dataは1つの文字列であり、それがモデルがドキュメントを受け取る理由です。フィールドが必要な場合は、指示でそれらを要求するか、自分で下流で解析してください。

結論

コネクタは1つの操作と1つのヘッダーです。ChatGPTはAPIキーMCPサーバーを受け入れません — それはプラットフォームの制限であり、OAuthチャレンジなしの401、メタデータがあるはずの3つの404、OpenAIの声明によって確認されています — だからメカニズムはアクションであり、メカニズムは難しい部分ではありません。

うまく機能するかどうかを決定する二つの選択肢はどちらも小さいです。カスタムヘッダーをx-api-tokenに設定してください。なぜなら、Bearerデフォルトはセットアップ時ではなく呼び出し時に失敗するからです。そして、response_typeをmarkdownに、js_render: trueと一緒に設定してください。なぜなら、8,676文字のMarkdownには50,403文字のHTMLが持たない思考の余地が残っており、また、見かけ上真っ当なoutputFormatが受け入れられ、無視され、より大きな方を返すからです。

コードからではなくGPTから駆動される同じAPIについては、私たちのChatGPTウェブスクレイピングガイドはモデルプラスフェッチパターンをカバーし、Universal Scraping APIページは操作の背後にあるアクターを説明し、ドキュメントはすべてのパラメーター参照を持ち、価格は各呼び出しのコストを示します。

ChatGPTにあなたが制御するフェッチを与える準備はできましたか？ Scrapelessの無料プランから始めてスキーマを貼り付けてください。

FAQ

Q: ChatGPTはMCPサーバーに接続できますか？
はい、しかしOAuth 2.1を使用している場合か、認証なしのみです。開発者モードのコネクタは静的なAPIキーを提示できず、これはOpenAIのドキュメントに明記されています。 x-api-tokenヘッダーで認証し、OAuthメタデータを公開しないScrapeless MCPエンドポイントのようなサーバーは、ChatGPTコネクタとして追加できません — GPTアクションがサポートされるルートです。

Q: なぜ私のGPTアクションは401を返すのですか？

最も多いのはヘッダー名です。APIキーの認証タイプはデフォルトでBearerとなり、Authorization: Bearer <key>を送信します; Scrapelessはx-api-tokenを読み取ります。認証タイプをカスタムに設定し、ヘッダー名をx-api-tokenにします。スキーマはどちらにしても検証されるため、これはセットアップではなく最初の呼び出しで表面化します。

Q: GPTアクションにはどのOpenAPIバージョンが必要ですか？

上記のスキーマはOpenAPI 3.1.0であり、その仕様に対して検証されます。ドキュメントを最小限に保ちます — サーバーのURL、明示的なoperationId値、および不要な$ref間接参照は含まない — なぜならビルダーのパーサーはより厳格で、エラーが専用バリデーターよりも特定的でないからです。

Q: アクションがモデルのコンテキストを埋めるのをどうやって止めることができますか？

Markdownを返します。response_typeをmarkdownに設定し、同じリクエスト内にjs_render: trueを含めることで、50,403文字から8,676文字にページのサイズが変わり、アクションの応答は会話のコンテキスト予算から消費されます。また、スキーマも狭くします: 小さなパラメーターセットを持つ1つの操作はモデルが高価な呼び出しを構築するための余地を減らします。

Q: なぜ私のoutputFormatパラメーターは何もしなかったのですか？

それは演者が読むパラメーターではないからです。リクエストは依然としてHTTP 200を返し、完全なHTML — 50,403文字ではなく8,676文字 — を返しました。正しいキーはresponse_typeであり、その横にjs_render: trueが必要です。未知のキーはここで拒否されるのではなく無視されるため、フォーマット設定が効果を持たないように見えるときは、戻ってきたもののサイズを確認してください。

Q: 1つのアクションが複数のScrapeless機能を公開することはできますか？

はい — 同じドキュメント内の操作ごとにパスとoperationIdを追加します。それぞれを狭く保ち、enum制約を守ってください。なぜなら、自由形式の演者フィールドを持つ単一の操作がモデルに推測を促すからです。最小特権にすることで、後でアクションのレビューが容易になります。

Q: これは通常のChatGPTの会話で機能しますか、それともカスタムGPTだけですか？

アクションはあなたが設定するGPTに属しているため、その能力は全ての会話ではなく、そのGPTに存在します。誰かと共有すると、その人はその操作を得ます; 自分のキーを提供するかどうかは、あなたが認証をどのように設定するかに依存します。