メインコンテンツまでスキップ

アプリをMCPツールに接続する

system.aiスキーマのMCPおよび登録するMCPを含む、Model Context Protocol (MCP) サーバー上に独自のアプリを構築します。アプリは、サインインしたユーザーとしてツールを呼び出します。Unity Gateway ガバナンスは、各ユーザーが呼び出すことができるMCPとツールを制御します。

アプリを Databricks Appsでランする場合は、ユーザー認可を使用してください。アプリが外部IDプロバイダーを使用してユーザーをサインインさせる場合、OAuthトークンフェデレーションを使用してDatabricksトークンを取得してください。このガイドは、複数のユーザーにサービスを提供するアプリを対象としています。独自の資格情報を使用してローカルでエージェントを構築およびテストするには、「PythonエージェントからMCPツールを呼び出す」を参照してください。

ユーザーごとの OAuth を使用する MCP の場合、ユーザーは外部プロバイダーアカウントも認証します。以下のステップでは、Databricks トークンの取得とプロバイダーサインインの完了の両方について説明します。

認証とアクセスの設定​

コードを追加する前に、ユーザーに MCP へのアクセス権を付与し、アプリの認証を構成してください。

MCPへのユーザーアクセスを許可する​

これらの要件は、両方の認証方法に適用されます。

  • 各ユーザーを Databricks ワークスペースに追加します。コンシューマーアクセスは、Unity Gateway を介して MCP を呼び出すのに十分です。
  • 各ユーザーにMCP上の EXECUTE を付与し、さらにその親カタログとスキーマ上の USE CATALOG と USE SCHEMA を付与します。MCPの共有を参照してください。

アプリの認証を設定​

アプリに一致するオプションを選択します:

  1. アプリのユーザー認証を有効にします。アプリは、トークン交換やアカウントフェデレーションポリシーを使用せずに、転送されたDatabricksユーザートークンを直接使用します。
  2. ユーザー認可スコープを追加します:ツール呼び出しにはai-gateway、検出およびサインインステータスAPIにはunity-catalogです。
  3. 各ユーザーにアプリの使用権 を付与します。

アプリのサーバーもワークスペースに到達できる必要があります。IPアクセスリストが有効な場合、そのアウトバウンドIPを許可してください。MCPネットワークを参照してください。

system.ai.dbsql, system.ai.sandbox, および system.ai.web_search は ベータ版 です。それらを使用するには、アカウント管理者がアカウントコンソールの プレビュー ページから 強化された Unity Gateway プレビューを有効化する必要があります。Unity Gateway 自体は一般提供されています。「アカウントプレビューの管理」を参照してください。

アプリをセットアップする​

これらのステップを通して、トークンとクライアントをサインインしたユーザー固有のものにしてください。

ユーザーのDatabricksトークンを取得します​

アプリがユーザーを認証する方法に一致するオプションを選択してください。どちらのオプションでも、残りのステップでdatabricks_tokenが提供されます。

Databricks Appsは、ユーザーのDatabricksトークンを x-forwarded-access-token リクエストヘッダーで提供します。そのトークンを直接使用します。アプリでトークン交換を実行する必要はありません。

現在のリクエスト内のトークンを読み取ります。たとえば、Flaskのリクエストハンドラーの場合:

Python
from flask import request

databricks_token = request.headers.get("x-forwarded-access-token")
if not databricks_token:
raise ValueError("A Databricks user token is required.")

その他のフレームワークについては、「ユーザー認証資格情報の取得」を参照してください。

MCP の一覧表示​

ユーザーがスキーマ内でアクセスできるMCPをリストします。Databricks提供のMCPについては、schemas/system.aiを使用します。登録済みMCPについては、schemas/main.defaultのように登録されているスキーマを使用します。

SDKをインストールする:

Bash
pip install --upgrade databricks-sdk

ユーザーのトークンでクライアントを作成し、MCPを一覧表示します。

Python
from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient(
host="https://<workspace-hostname>",
token=databricks_token,
auth_type="pat",
)

for service in workspace_client.ai_gateway.list_mcp_services(parent="schemas/system.ai"):
print(service.name)

SDK設定auth_type="pat"は、アプリの環境認証情報ではなく、提供されたトークンを選択します。提供されたトークンは、依然としてユーザーのOAuthトークンです。各ユーザーに対してWorkspaceClientを作成し、すべての呼び出しでそのユーザーのトークンが使用されるようにします。以下のステップでworkspace_clientを再利用します。SDKはページネーションを自動的に処理します。

各 name は、mcp-services/system.ai.githubのような形式 mcp-services/<catalog>.<schema>.<service> のリソースパスです。それを変更せずにサインインステータスAPIに渡し、それを使用して ツールを呼び出す のMCP URLを作成します。MCPサービスのリスト を参照してください。

ユーザーのサインインステータスを確認する​

アプリで使用する各MCPを確認してください。レスポンスには、MCPがユーザーごとのOAuthを使用しているかどうかが表示され、使用している場合は、ユーザーが外部プロバイダーにサインインしているかどうかが表示されます:

MCPのユーザー資格情報を取得します:

Python
from databricks.sdk.errors import InvalidParameterValue, NotFound
from databricks.sdk.service.catalog import ProvisioningInfoState

mcp_name = service.name # From List MCPs, for example "mcp-services/system.ai.github"

needs_sign_in = True
try:
credential = workspace_client.ai_gateway.get_mcp_service_user_mapped_credential(
name=mcp_name
)
signed_in = (
credential.provisioning_info is not None
and credential.provisioning_info.state == ProvisioningInfoState.ACTIVE
)
except NotFound:
signed_in = False
except InvalidParameterValue:
# The MCP doesn't use per-user OAuth.
needs_sign_in = False
signed_in = True
  • provisioning_info.stateがACTIVEの場合、ユーザーはサインインしています。ツールを呼び出すに移動します。
  • リクエストがNOT_FOUNDを返すか、状態がACTIVE以外の場合は、MCPのサインインボタンを表示します。
  • リクエストが INVALID_PARAMETER_VALUE を返した場合、MCPはユーザーごとのOAuthを使用しないため、ユーザーはサインインする必要はありません。これは、DatabricksデータとツールMCPsの場合です。ツールの呼び出しに移動します。

呼び出し元の資格情報を取得するを参照してください。

ユーザーをプロバイダーにサインインさせる​

ユーザーがサインインボタンをクリックすると、ポップアップでMCPの サインインページ を開きます。このページの name パラメーターは、 mcp-services/ プレフィックスのないMCP名です( system.ai.github など)。ユーザーはそのページでサインインし、プロバイダーの同意画面でアクセスを許可します。

JavaScript
// mcpName is the MCP name without the mcp-services/ prefix, for example "system.ai.github"
const signInUrl = `https://${workspaceHostname}/mcp-service-login?name=${encodeURIComponent(mcpName)}`;
window.open(signInUrl, 'mcp-sign-in', 'popup,width=600,height=700');

サインインページは、アプリにメッセージを返しません。サインインが終了したタイミングを検出するには、ユーザーがアプリに戻ったときにサインインステータスをもう一度確認します。

サインインページは、ユーザーの Databricks ブラウザーセッションを使用します。ユーザーがそのブラウザーでワークスペースにサインインしていない場合、 Databricks は最初にサインインするように要求します。プロバイダークレデンシャルは、ページにサインインしているユーザーに対して保存されるため、そのユーザーはアプリが動作するユーザーと同じである必要があります。

ツールを呼び出す​

MCPのリクエストをユーザーのDatabricksトークンでMCPのURLに送信します。MCPのURLはhttps://<workspace-hostname>/ai-gateway/の後にMCPのリストの名前が続くもの、例えばhttps://<workspace-hostname>/ai-gateway/mcp-services/system.ai.githubです。

アプリは、このステップで示すようにツールを直接呼び出すか、どのツールを呼び出すかを決定するエージェントにそれらを与えることができます。エージェントをランするには、 ステップ3: これらのツールを使ってエージェントをランするに従い、 MCPの一覧表示でユーザーのトークンを使って作成した workspace_client を渡します。これにより、エージェントはそのユーザーとしてツールを呼び出します。エージェントフレームワークは MCP Python SDK のバージョン 1 を使用するため、そのページにリストされているパッケージをインストールします。

パッケージをインストールします:

Bash
pip install --upgrade databricks-mcp

MCPの一覧表示からユーザーの workspace_client に接続し、ツールを一覧表示して呼び出します:

Python
from databricks_mcp import DatabricksMCPClient

mcp_name = "mcp-services/system.ai.github" # A name from List MCPs

mcp_client = DatabricksMCPClient(
server_url=f"https://<workspace-hostname>/ai-gateway/{mcp_name}",
workspace_client=workspace_client,
)

for tool in mcp_client.list_tools():
print(f"{tool.name}: {tool.description}")

result = mcp_client.call_tool("<tool-name>", arguments={})
print(result.isError)
print(result.content)

ツールを呼び出す前に、list_tools()を使用してツール名と入力スキーマを確認し、各結果がエラーかどうかを確認してください:databricks-mcpを使用したresult.isError、またはバージョン2のMCP Python SDKを使用したresult.is_errorです。結果の読み取り方法については、ツールを直接呼び出してトラブルシューティングするをご覧ください。ツールリストが空の場合、または接続に失敗した場合は、MCP認証をご覧ください。

その他のリソース​