MCP 連携ガイド | Manager AGI

認可ログイン結果の返却

SDK をインストールします：

pnpm add mcp-auth-web

API 環境（engineUrl はパスなしのベース URL）：

テスト環境: https://aim-api-test.proton-system.com
本番環境: https://aim-api.proton-system.com

認可結果の返却先 URL: https://xxx.com/openapi/v1/mcp/authorization/callback

パスは SDK が自動で追加します。

ログイン成功後に認証情報を返します：

import { createMcpAuthClient } from 'mcp-auth-web'

const mcpAuth = createMcpAuthClient({
  engineUrl: 'https://aim-api-test.proton-system.com',
})

mcpAuth.complete({
  Authorization: `Bearer ${token}`,
})

ログイン失敗またはキャンセル時：

mcpAuth.fail({ code, message })
mcpAuth.cancel()

mcp-auth-web@0.3.1 以降、getMcpAuthErrorMessage(error) は SDK が管理する安全な中国語の既定メッセージを返します。表示は接続先の UI が担当し、翻訳はエラーコードに基づいて変更できます。complete()、fail()、cancel() の例外を捕捉してください。complete() の catch で無条件に fail() を呼ばず、生の例外に含まれる認証情報や認可 URL を表示しないでください。

import { getMcpAuthErrorMessage } from 'mcp-auth-web'

try {
  mcpAuth.complete({ Authorization: `Bearer ${token}` })
} catch (error) {
  message.error(getMcpAuthErrorMessage(error))
}

engineUrl はプラットフォームから提供される Engine のアドレスです。complete には MCP が実際に使う認証 Header を直接指定します。SDK は Authorization の Bearer JWT から exp を読み取り、expiresAt を自動生成するため、有効期限を渡す必要はありません。

SDK は HTTPS コールバックと既存の App 認可ウィンドウを自動で選択します。mcp-auth-web@0.3.0 では complete の入力形式が変更されています。旧版から更新する場合は、headers ラッパーと手動指定の expiresAt を削除してください。engineUrl を省略すると、既存の App 認可ウィンドウを引き続き使用します。

メソッドが false を返した場合、現在のページには利用可能な返却方法がありません：

if (!mcpAuth.isAvailable()) {
  message.error('現在の環境では認可結果を返却できません')
}

App から認可を開始してログインを完了し、App に戻って「認可済み」と表示されれば成功です。本番のログインページと Engine は、端末から到達できる有効な証明書の HTTPS を使用してください。認証情報や認可 URL をログに記録しないでください。

Tool 共通のリスク注釈

読み取り Tool：

annotations: {
  readOnlyHint: true
}

書き込み Tool：

annotations: {
  destructiveHint: true
}

Tool の種類

1. 一覧 Tool

Tool が候補を返し、ユーザーの選択値を別の Tool のパラメーターへ設定する場合は、outputSchema のルートに次を追加します。

outputSchema: {
  type: "object",
  properties: {...}, // 省略可能
  "x-prerequisiteCandidate": {
    itemsPath: "data",
    valuePath: "id",
    labelPath: "name"
  }
}

3 つのフィールドの意味：

itemsPath: Tool の結果内にある候補配列の場所。
valuePath: 各候補から最終的に設定する値のフィールド。
labelPath: 各候補からユーザーに表示するフィールド。

たとえば Tool が次を返す場合：

{
  "data": [
    { "id": "1", "name": "店舗 A" },
    { "id": "2", "name": "店舗 B" }
  ]
}

この場合：

itemsPath: "data" は、候補一覧が結果の data 配列であることを示します。
valuePath: "id" は、選択した項目の id を対象 Tool に設定することを示します。
labelPath: "name" は、選択カードに項目の name を表示することを示します。

チェックリスト