Dureach

MCP経由でAIクライアントを接続する

外部MCPクライアントをStreamable HTTPでDureachに接続し、OAuth同意を完了して、tools/listとtools/callを安全に呼び出す方法を説明します。

Dureachは、外部MCPクライアント向けにhttps://app.dureach.com/mcpで読み取りとアクション用のMCPサーバーを公開しています。クライアントはOAuth同意を完了し、tools/listで付与されたツールを検出した後、dureach.*ツール名と型付き引数でtools/callを呼び出します。

ツールの結果は外部クライアントに転送され、その提供者が処理または保存する場合があります。接続前に提供者のデータ処理、保存、アクセスに関する条件を確認してください。業務に必要な項目だけを要求し、連絡先情報や顧客レコードを共有会話、スクリーンショット、ログに含めないでください。

接続前に必要なものは何ですか

  1. エージェントプラットフォーム機能が有効なDureachワークスペースが必要です。有効でない場合、アドミッション判定はplan_capability_requiredを返します。
  2. ブラウザ同意グラントを完了できるOAuthクライアント。MCPはOAuthベアラートークンのみを受け付けます。REST APIキーは/mcpでは拒否されます。
  3. ワークスペースのメンバーとしてブラウザーで同意を完了してください。 認証情報はクライアントの保護された認証情報ストアかサーバー側のシークレット管理サービスに保存してください。トークンを会話、共有文書、スクリーンショット、問い合わせに貼り付けないでください。
  4. JSON応答を伴うStreamable HTTPに対応したMCPクライアント（たとえばMCPコネクタ付きのClaude Desktop、Cursor、またはmcp SDKで構築したカスタムPythonクライアント）。

MCPのOAuth同意はどのように動作しますか

  1. OAuthクライアントを登録または開き、ワークスペースの認可グラントを開始します。
  2. クライアントに必要なスコープのみを選択します（MCPの承認、ポリシー、クォータを参照）。レポート用クライアントはcompanies:readとtrade:readのみで足りる場合があり、アウトリーチ用クライアントは追加でleads:createまたはemails:sendの付与が必要です。
  3. ワークスペースのメンバーとしてブラウザーで同意を完了してください。 認証情報はクライアントの保護された認証情報ストアかサーバー側のシークレット管理サービスに保存してください。トークンを会話、共有文書、スクリーンショット、問い合わせに貼り付けないでください。
  4. すべてのMCP HTTPリクエストでトークンをAuthorization: Bearer YOUR_OAUTH_ACCESS_TOKENとして送信します。URL、スクリーンショット、ログ、チケットには含めないでください。
  5. クライアントが特定のワークスペースとして動作する必要がある場合は、トークンのワークスペースIDとともにX-Workspace-IDを送信します。不一致の値はworkspace_context_requiredを返します。

クライアントライブラリが検出用の値を必要とする場合は、/.well-known/oauth-protected-resource/mcpにあるメタデータ文書を確認してください。

クライアントが使用するエンドポイントとプロトコルは何ですか

  • streamable HTTP に対応する MCP クライアントで https://app.dureach.com/mcp を正確に指定してください。
  • 対象ワークスペースの OAuth 同意を完了し、認証情報はクライアントの保護された認証情報ストアまたはサーバー側のシークレット管理サービスに保存してください。
  • ホストやオリジンが拒否された場合は接続先 URL を確認し、サポートに連絡してください。拒否を回避するためにセキュリティヘッダーを削除したり偽装したりしないでください。
  • 調査のために応答の request_id を保存し、共有ログにトークンや結果行を含めないでください。

利用可能なツールを一覧表示する方法

OAuth 同意後に tools/list を呼び出してください。利用可能な各ツールには名前と引数のスキーマが含まれます。呼び出し前に、返されたスキーマでリクエストを検証してください。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

tools/list で接続に利用できるツールを確認してください。利用範囲は付与された権限とワークスペースの利用資格によって異なります。読み取り権限から始め、不足する権限は管理者に確認してください。広範な権限を要求しないでください。

ツールを呼び出す方法

完全なdureach.名と引数オブジェクトを含むtools/callリクエストを送信します。不明な名前や接頭辞のない名前はUnknown tool（INVALID_PARAMS）を返します。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "dureach.companies.search",
    "arguments": {"query": "industrial valves", "page": 1, "limit": 10}
  }
}

成功した結果は、JSONを含むテキスト形式の項目1件と、解析済みのstructuredContentコピーを返します。アプリケーション障害はisError: trueと{"error": {"code": "...", "details": {...}}, "request_id": "..."}を返します。サポートと再試行処理のためにrequest_idを保存してください。引数の上限一覧はMCPツールリファレンスに記載されています。

一般的なクライアントを設定する方法

Claude Desktopまたはその他のコネクタ型クライアント

  1. URLhttps://app.dureach.com/mcpでStreamable HTTPサーバーを追加します。
  2. Dureach OAuth登録のクライアントIDとMCPリソースメタデータURLでOAuth認証を設定します。
  3. 同意を完了し、コネクタがdureach.で始まるツールを一覧表示することを確認します。
  4. データ検索を実行する前に、dureach.workspace.contextとdureach.workspace.capabilitiesから開始します。

カスタムPythonクライアント（公式mcp SDK）

import os

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://app.dureach.com/mcp"
TOKEN = os.environ["DUREACH_OAUTH_ACCESS_TOKEN"]

async def main():
    async with streamable_http_client(
        MCP_URL, headers={"Authorization": f"Bearer {TOKEN}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool(
                "dureach.companies.search",
                {"query": "industrial valves", "page": 1, "limit": 10},
            )
            print("Search completed")

トークンとクエリは実際の値に置き換えてください。トークンをソース管理にコミットしないでください。

アクセスを共有する前に実行すべき確認事項は何ですか

  1. dureach.workspace.contextを呼び出し、返されたワークスペースIDとスコープが意図したワークスペースと一致することを確認します。
  2. dureach.workspace.capabilitiesを呼び出し、想定したアクションのみが表示されることを確認します。
  3. 範囲を限定した読み取りを1件実行し（たとえばlimit: 5付きのcompanies.search）、ページネーションフィールドを確認します。
  4. 書き込み経路では、最初にdry_run: trueで実行します。MCPの承認、ポリシー、クォータを参照してください。
  5. アクセスが不要になったら、/oauth/revokeまたはSettings → Integrationsでトークンを取り消します。

関連ページ