Salesforce Headless MCP AI

本番向けの Frappe v15+ アプリケーションで、承認された各 Frappe ユーザーに、設定可能な AI プロバイダーと Salesforce Hosted MCP をバックエンドとする Web AI アシスタントを提供します。Salesforce OAuth トークンと AI API キーは Frappe サーバー上で暗号化されたまま保持され、ブラウザコードは許可された Frappe メソッドのみを呼び出します。

Salesforce Headless 360 MCP は現在 Salesforce のベータサービスです。本番環境で使用する前に、貴社組織での提供状況、制限、利用規約を確認してください。

プロジェクトドキュメント

• 開発技術ドキュメント

• 完全なプロジェクトプレゼンテーションスクリプト

Related MCP server: Salesforce MCP Server

アーキテクチャ

Frappe browser page (/salesforce-ai)
        ↓ authenticated frappe.call
Frappe Python services
        ├── OpenAI / Claude / Gemini / Azure / local LLM (tool calling)
        └── Salesforce Hosted MCP (Streamable HTTP + OAuth bearer token)
                    ↓
              Salesforce org

MCP ツールリストは実行時に取得されます。読み取り専用モードでは、サーバーは discover、describe、dispatch_readonly のみを許可し、dispatch はモデルのツールから除外され、Python 側でも独立してブロックされます。書き込みが有効な場合、dispatch はユーザーが明示的に確認するまで、ユーザーに紐づく10分間の確認レコードに保持されます。

このアプリは Salesforce SObject サーバーもサポートしています。platform/sobject-all の場合、読み取り専用モードでは、読み取り専用とマークされたツールのみが公開されます（さらに Salesforce の既知のスキーマ/クエリ/検索/ID/リレーションシップの読み取りツールも公開されます）。書き込みが有効な場合、検出された変更ツールが公開され、すべての create/update/delete 呼び出しには同じ確認ゲートが適用されます。

要件

• Frappe Framework v15 以降と動作する Bench サイト

• Python 3.10+

• API v67.0+ と Headless 360 が有効化された Salesforce 組織

• OAuth Authorization Code + PKCE S256 用に設定された Salesforce External Client App

• 設定済みモデルにアクセスできる OpenAI API キー

• 公開 Frappe サイト用の HTTPS

Python の依存関係（httpx と openai）は pyproject.toml で宣言され、アプリとともにインストールされます。

インストール

cd ~/frappe-bench
bench get-app https://github.com/TechwithZakir/salesforce_mcp_ai
bench --site yoursite.example install-app salesforce_mcp_ai
bench --site yoursite.example migrate
bench build --app salesforce_mcp_ai
bench restart

ローカル開発の場合:

cd ~/frappe-bench
bench new-app salesforce_mcp_ai
# Replace the generated app with this repository, or clone it into apps/salesforce_mcp_ai.
bench --site development.localhost install-app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

Salesforce MCP Manager を管理者に割り当て、Salesforce MCP User をワークショップユーザーに割り当てます。マネージャーとして Salesforce MCP Settings を開いて設定を保存し、その後 /salesforce-ai にアクセスしてください。

既存インストールをアップグレードした後は、bench --site yoursite.example migrate と bench --site yoursite.example clear-cache を実行してください。その後、公開の Salesforce MCP AI ワークスペースが、Salesforce MCP User、Salesforce MCP Manager、または System Manager を割り当てられたユーザー向けに Desk に表示されます。

Salesforce の設定

1. Salesforce 設定で MCP Servers を検索します。

2. MCP Servers を選択し、headless-360 を見つけて有効化します。

3. External Client App Manager に移動し、External Client App を作成します。

4. OAuth Authorization Code フローを有効にし、S256 を使用した PKCE を要求します。

5. スコープ mcp_api、refresh_token、offline_access を追加します（ご利用の Salesforce リリースで公開されているラベル/オプションを使用してください）。

6. コールバック URL を正確に次のように設定します:

https://YOUR-FRAPPE-DOMAIN/api/method/salesforce_mcp_ai.api.auth.salesforce_callback

7. コンシューマーキーと、アプリのポリシーで要求される場合はクライアントシークレットを Salesforce MCP Settings にコピーします。

Salesforce は、すべての MCP 操作に対して、接続ユーザーの CRUD、フィールドレベルセキュリティ、共有設定、プロファイル、権限セットを適用します。ワークショップユーザーには、必要な Salesforce 権限のみを付与してください。

設定

推奨される本番設定:

Enabled:                         On
AI Provider:                     OpenAI
API Key:                         (encrypted)
Model:                           gpt-5.6
Temperature:                     0.2
Max Tokens:                      4000
Salesforce Login URL:            https://login.salesforce.com
Salesforce MCP URL:              https://api.salesforce.com/platform/mcp/v1/platform/headless-360
Allow Write Operations:          Off
Require Write Confirmation:      On
Enable MCP Trace:                On
Enable Audit Logging:            On
Maximum MCP Tool Calls:          6
Request Timeout:                 60

OpenAI API キーと External Client App のクライアントシークレットは、Frappe の Password フィールドです。アクセストークンとリフレッシュトークンも、ユーザーごとの Salesforce Connection ドキュメント上の Password フィールドです。これらは、Frappe の暗号化パスワード API を使用してバックエンドコードのみが読み取ります。

サンドボックス

コード変更なしで切り替える:

Salesforce Login URL: https://test.salesforce.com
Salesforce MCP URL:   https://api.salesforce.com/platform/mcp/v1/sandbox/platform/headless-360

同じコールバックとスコープを持つサンドボックス用 External Client App を使用します。

SObject All サーバー

Salesforce 設定 → MCP Servers で SObject All を有効化し、次のように設定します:

Production/Developer org: https://api.salesforce.com/platform/mcp/v1/platform/sobject-all
Sandbox/Scratch org:      https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all

Cases、Opportunities、Accounts、その他のレコードを照会する場合は読み取り専用モードを使用します。create/update/delete 操作が必要な場合にのみ書き込みを有効にし、確認は通常は有効のままにしておく必要があります。

AI プロバイダーの設定

Salesforce MCP Settings で1つのプロバイダーを選択します:

• OpenAI: OpenAI API キーとモデルを入力します。

• Claude: Anthropic API キーと Claude モデル名を入力します。

• Gemini: Gemini API キーとモデル名を入力します。

• Azure OpenAI: キー、HTTPS リソースエンドポイント、デプロイメント名を入力します。現在の v1 エンドポイントが使用されます。

• Local LLM（OpenAI 互換）: OpenAI 互換の /v1 ベース URL とモデル名を入力します。セキュリティ保護されていないループバックサーバーでは、キーは空白でもかまいません。

ローカルサーバーの例:

Ollama:    http://127.0.0.1:11434/v1
LM Studio: http://127.0.0.1:1234/v1
LiteLLM:   https://llm.example.com/v1
vLLM:      https://vllm.example.com/v1

選択したモデルはツール/関数呼び出しをサポートしている必要があります。ローカル HTTP はループバックホスト名またはアドレスに対してのみ許可され、リモートエンドポイントには HTTPS が必要です。エージェントは固定の安全指示と、動的に返されポリシーでフィルタリングされた MCP スキーマのみを送信します。最大値は単なる反復回数ではなく、個々のツール呼び出し全体でカウントされます。

セキュリティと本番運用に関する注意事項

• 変更が必要でない限り、Allow Write Operations はオフにしておきます。書き込みがオンのときは確認を有効のままにします。

• OAuth ステートと PKCE verifier はサーバーキャッシュエントリで、10分後に失効し、一度だけ使用されます。

• 保留中の書き込みはユーザーに紐づき、一度だけ使用でき、10分後に失効します。

• 設定された MCP ホストは SSRF リスクを減らすため、api.salesforce.com 上の HTTPS に制限されます。

• 認証エラーが発生すると、リフレッシュは正確に1回だけ試行されます。リフレッシュに失敗するとアカウントは切断されます。

• 監査ペイロードは編集（redact）および切り詰められます。トレースやカスタムログにシークレットフィールドを追加しないでください。

• Frappe は HTTPS でのみ提供し、Redis と暗号化キーを保護し、シークレットをローテーションし、制限的なロールを使用し、バックアップを設定してください。

• Salesforce データを LLM に送信する前に、Salesforce Beta の利用規約と組織のデータ取り扱いポリシーを確認してください。

• 通常のチャットは、ワークショップでのわかりやすさのため同期です。サービス クラスは分離されているため、後でエンドポイントから frappe.enqueue を通じて呼び出すことができます。

権限

• Salesforce MCP User: アシスタントを使用し、自分の Salesforce アカウントを接続/切断し、自分のログのみを表示できます。

• Salesforce MCP Manager: 設定を構成し、すべての監査ログ/接続を表示できます。シークレット値が API から返されることはありません。

所有権は DocType 権限フックと、各許可済みメソッドのフィルターによって強制されます。

テストと検証

テストはモックを使用し、実際の Salesforce 組織や OpenAI 呼び出しは必要ありません:

bench --site development.localhost run-tests --app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

カバレッジには、PKCE、ワンタイム OAuth ステート、トークンリフレッシュ、読み取り専用ツールのフィルタリングとブロック、接続/ログの所有権、ツール呼び出し数の上限設定が含まれます。リリース時には、専用の Salesforce テストユーザーに対して、/salesforce-ai、OAuth コールバック、ツールディスカバリ、読み取り専用プロンプト1件のブラウザスモークテストも実行してください。

ワークショップデモ

1. Salesforce MCP User ロールを持つユーザーとしてサインインします。

2. /salesforce-ai を開き、Connect Salesforce をクリックして OAuth を完了します。

3. バッジが緑色で、モードが Read Only と表示され、MCP ツールが表示されることを確認します。

4. 「Acme Corporation を探して。」と尋ねます。トレースを展開して discover、describe、dispatch_readonly を表示します。

5. 「そのオープンな商談を表示して。」と尋ね、次に「どの商談を優先すべきですか？」と尋ねます。

6. 必要に応じてマネージャーとして書き込みを有効にします。フォローアップタスクの作成を依頼し、提案された dispatch 引数を確認して、Confirm & Execute をクリックします。

7. Salesforce MCP Log を開いて、切り詰められた監査証跡を表示します。

トラブルシューティング

• OAuth state invalid or expired: Connect Salesforce を再起動し、10分以内に完了してください。Redis/キャッシュの健全性と、コールバックが同じ Frappe デプロイメントに戻ることを確認してください。

• redirect_uri mismatch: 上記のコールバックをスキームとホスト名を含めて正確にコピーしてください。

• invalid scope / MCP access denied: Headless 360 を有効化し、API v67.0+、mcp_api スコープ、ユーザーの Salesforce 権限を確認してください。

• 401 after connection: リフレッシュに失敗した場合は再接続してください。External Client App のリフレッシュトークンポリシーとクライアントシークレット要件を確認してください。

• No MCP tools: 設定済みの本番/サンドボックスエンドポイントとサーバーの有効化を確認してください。

• OpenAI error: API キー、モデルアクセス、割り当て、アウトバウンドネットワークアクセス、タイムアウトを確認してください。

• Maximum tool calls reached: プロンプトをより具体的にするか、制限を慎重に引き上げてください（このアプリが受け入れる最大値は20です）。

• Page redirects to login / permission denied: サインインし、Salesforce MCP ロールのいずれかを割り当ててください。

技術的な障害は frappe.log_error で記録されます。ブラウザの応答にはスタックトレースやシークレットは含まれません。

ソースレイアウト

salesforce_mcp_ai/
├── api/          # whitelisted auth, MCP, and agent methods
├── services/     # OAuth, token, MCP transport, OpenAI orchestration
├── utils/        # PKCE, validation, redaction
├── salesforce_mcp_ai/doctype/
├── tests/
└── www/salesforce-ai/

ライセンス

MIT