CursorでSalesforce Hosted MCPに接続！スクラッチ環境構築でのエラーと解消法

Blog Salesforce 開発者体験

はじめに

こんにちは。株式会社ユーザベース Speeda事業の佐藤、小原、阿波連、長岡です。 *1

2026/04/14にGAされた Salesforce Hosted MCP Servers について、スクラッチ環境への接続で一部ハマりどころがありました。 本記事では、接続方法、接続トラブルの原因とその具体的な回避策について、備忘録を兼ねて共有します。

手順

Cursorからスクラッチ組織のMCPサーバーに接続していきます。
スクラッチ組織の作成方法は割愛します。 公式ドキュメントの手順はこちらです。

  1. スクラッチ環境でメールの検証済み状況を確認
    1. 「設定 > ユーザー」 から、自身のユーザーの詳細を開く
    2. 「ユーザーの詳細 > メール」 から横にある[検証済み] の表示を確認
    3. 検証済みでない場合は、 [検証] リンク（またはボタン）をクリックして検証を行う
  2. 未検証ドメインの置換設定の有効化
    1. 「設定 > メール > 送信」から送信を開く
    2. 設定項目の中にある [Use a substitute email address for unverified domains] （未検証のメール送信ドメインを置換）のチェックボックスをオンにして保存
  3. スクラッチ環境の外部アプリケーション設定
    1. 「設定 > 外部クライアント」で検索、外部クライアントアプリケーションマネージャーを開く
    2. 「新規外部クライアントアプリケーション」ボタンをクリック
    3. 基本情報の必須項目を入力
      1. 外部クライアントアプリケーション名：任意の名前（例：CursorMCP）
      2. API 参照名：任意の名前（例：CursorMCP）
      3. 取引先責任者 メール：MCP利用者のメールアドレス
    4. API（OAuth設定の有効化）を設定
      1. OAuthを有効化にチェック
      2. コールバック URL：「cursor://anysphere.cursor-mcp/oauth/callback」
      3. OAuth 範囲：「mcp_api」「refresh_token」の2点を範囲として選択
      4. セキュリティで以下2点にチェック（※他はチェックを外す）
        1. サポートされる認証フローに Proof Key for Code Exchange (PKCE) 拡張を要求
        2. 指名ユーザーの JSON Web トークン (JWT) ベースのアクセストークンを発行
    5. 画面下部の作成ボタンをクリック
    6. 作成した外部クライアントアプリケーションをクリックし、設定タブを開く
    7. OAuth設定のアプリケーション設定「コンシューマー鍵と秘密」ボタンをクリック
    8. メールに届く確認コードを指定し認証
    9. 表示された「コンシューマー鍵」をコピーして控えておく
  4. スクラッチ環境のMCPを有効化
    1. 「設定 > MCP」で検索、MCPサーバーを開く
    2. 「sobject-all」など使いたいものをクリックして詳細から有効化
    3. 有効化したMCPサーバーのServer URLをコピーして控えておく
  5. IDEからMCPの設定（Cursor + スクラッチ環境用）
    1. Cursor設定から「Tools ＆ MCP」を開く
    2. 新しくMCPサーバーを追加するボタンからmcp.jsonを開く
    3. 以下の接続情報を記載追記して保存
      1. url： 手順4でコピーしたMCPサーバーのServer URL
      2. CLIENT_ID： 手順3でコピーしたコンシューマー鍵
{
  "mcpServers": {
    "Salesforce": {
      "url": "https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all",
      "auth": {
        "CLIENT_ID": "<CLIENT_ID>"
      }
    }
  }
}
  1. MCP接続認証
    1. スクラッチ環境のパスワードを確認
sf org display -o <alias>

　※<alias>：スクラッチ組織のalias

  1. 上記コマンドで表示されたUsername・Passwordを控える
    1. （Passwordが無い場合）SF CLIでスクラッチ環境ログインユーザーのパスワードを生成
sf org generate password --target-org <alias>
  1. 「Tools ＆ MCP」の設定画面に戻り、追加したMCP設定の「Connect」ボタンを押下
  2. ブラウザ上で開かれるログイン画面に、控えたUsername・Passwordを指定し検証
  3. 追加したMCPのステータスアイコンが、赤 or 黄色 ⇒ 緑色に変わって接続ができていることを確認

遭遇したエラーとその回避策

1. CLIENT_ID（コンシューマ詳細）取得時のエラー

  • 現象:
    外部クライアントアプリケーションの設定後、「コンシューマの詳細を表示（コンシューマ鍵と秘密）」を押下すると「An internal server error has occurred」が発生する。

  • 原因と対策:
    操作ユーザーのメールアドレスが未検証であることが原因です。

  • 解消方法:
    「設定 > ユーザー」から自身のユーザーを選択し、メールアドレスの検証（確認メールのリンククリック）を行ってください。検証完了後、再度「コンシューマの詳細」にアクセス可能になります。

  • 備考:
    本事象に解決方法については、パートナーコミュニティにて問い合わせを行い、サポートから提示いただいた方法となります。 「Spring '26 におけるメール送信ドメインの検証」に関する変更が影響し、本エラーが発生している可能性が高いとのことです。

2. Cursorからの接続エラー（invalid_client_id）

  • 現象:
    MCP接続情報を入力し、Cursorから「Connect」を押下すると以下のエラーが表示される。
    error=invalid\_client\_id\&error\_description=client%20identifier%20invalid

  • 原因と対策:
    Salesforce側で外部クライアントアプリケーションを作成・デプロイした後、メタデータが反映されるまでタイムラグがあるために発生します。

  • 解消方法:
    設定直後は認識されないことが多いため、30分程度待機してから再度リトライしてください。

3. 認証に使用するアカウントの確認

  • 現象:
    Cursorの「Connect」押下後に表示されるログイン画面で、どのアカウントを使用すべきかわからない。

  • 解消方法:
    接続先となるスクラッチ組織のアカウントでログインする必要があります。
    ※Dev Hub組織のアカウントではない点に注意してください。

    事前にSalesforce CLIでスクラッチ組織のパスワードを発行し、ログイン情報を確認しておきます。

# 1. パスワードの発行
sf org generate password -o <スクラッチ組織のエイリアス>

# 2. ログインユーザー名（Username）とパスワード（Password）の確認
sf org display -o <スクラッチ組織のエイリアス>

4. ログイン画面が開かない場合

  • 現象:
    「Connect」を押下しても、認証用のブラウザタブ（ログイン画面）が立ち上がらない、または意図しない組織に自動ログインされる。

  • 原因と対策:
    ブラウザですでに別のSalesforce組織にログインしている場合、セッションが干渉することがあります。

  • 解消方法1:
    一度すべてのSalesforce組織からログアウトした状態で再試行する。

  • 解消方法2（推奨）:
    ブラウザのキャッシュをクリアするか、デフォルトブラウザを一時的に「シークレットモード」のようなクリーンな状態にしてから試行してください。

MCPサーバーでできること

スクラッチ環境には8つのサーバーが用意されています。各MCPサーバーのツールをAIに読み込ませ説明してもらいました。

サーバー名 役割 ツールの内容
metadata-experts カスタムオブジェクトやフローなどのメタデータタイプに対して、呼び出し可能なアクションを実行する executeMetadataAction: メタデータタイプに対してアクションを実行する
salesforce-api-context SalesforceのToolingオブジェクトやメタデータに関する詳細なコンテキスト情報を取得する getContextToolingAndDataObject: フィールドの定義・有効な値・制約などを取得し、正確なファイルの生成を支援する
getMetadataTypeSections: 利用可能なセクションを確認
getMetadataTypeContext: コンテキスト情報を取得
getMetadataTypeFields / getMetadataTypeFieldsProperties: フィールドとプロパティを取得
searchMetadataTypes: 文字列でメタデータタイプを検索
data-cloud-queries Data Cloudのデータに対するクエリやメタデータ取得を行う postDcQuerySql: Data Cloud上でSQLクエリを実行し、メタデータやデータの最初のまとまりを取得する
getDcMetadata: データスペース内のすべてのエンティティをリスト表示する
sobject-reads Salesforceのレコードを読み取る（検索・取得）ための基本機能を提供する getRelatedRecords: リレーションをたどって親レコードから関連する子レコードを取得
listRecentSobjectRecords: ユーザーが最近閲覧・変更したレコードを取得
soqlQuery / find: SOQLで条件検索、SOSLで複数オブジェクト横断テキスト検索
getUserInfo / getObjectSchema: 現在のユーザー情報・LLM向けオブジェクトスキーマを取得
sobject-all sobject-readsのすべての読み取り機能に加えて、レコードの作成と更新を行う createSobjectRecord: 新しいレコードを作成
updateSobjectRecord / updateRelatedRecord: レコードIDを指定した更新や、親レコードからたどって関連する子レコードの更新を行う
sobject-deletes sobject-readsのすべての読み取り機能に加えて、レコードの削除を行う deleteSobjectRecord: 指定したIDのレコードを削除（ゴミ箱へ移動）
deleteRelatedRecord: 親レコードからたどって特定の子レコードを削除
sobject-mutations sobject-readsのすべての読み取り機能に加えて、レコードの変更（作成・更新）を行う（sobject-allの作成・更新機能と同様） createSobjectRecord / updateSobjectRecord / updateRelatedRecord: 新しいレコードの作成や、既存のレコード・関連レコードの更新を行う
engagement-interaction エンゲージメント（顧客との接点や対話）データに特化した管理機能を提供する fetchEngagementInteraction: エンゲージメントデータを取得
createEngagementInteraction: 作成
deleteEngagementInteraction: 削除

オブジェクトを読めるのは便利ですね。資料化したりダッシュボードにしたりと活用できるイメージがあります。

開発者視点ではmetadata-expertsが気になりました。AIエージェントから呼び出されることを前提としたInvocable Methodをユーザーに提供することもできるかもしれません。

おわりに

Salesforceが発表したHeadless 360で、これからのSalesforce開発環境ではさらにAIエージェントの利用が進んでいくと思います。スクラッチ組織へMCP接続することで開発者体験はより良いものに変わっていくでしょう。ぜひ本記事を参考にしてみてください。

参考文献

*1:この記事はモブで書いています

© Uzabase, Inc. All rights reserved.

Page top