Snappy MCP Server with Xano Integration

Xano 統合による Snappy MCP サーバー

ツール管理、セッション追跡、OAuth のために Xano データベースと連携する、Cloudflare Workers 上に構築されたリモート MCP サーバーです。最新の Streamable HTTP トランスポートプロトコル（2024-11-05）を完全にサポートしました。

ローカルで開発する

# clone the repository
git clone https://github.com/roboulos/remote-mcp-server.git

# install dependencies
cd remote-mcp-server
npm install

# Configure Xano API Key
# Add your Xano API key to wrangler.jsonc in the XANO_API_KEY variable

# run locally
npm run dev

ブラウザーで http://localhost:8787/ を開けるはずです。

MCP サーバーに接続する

MCP Inspector を使用する（レガシー）

古い SSE トランスポートを使用して新しい MCP API を試すには、MCP Inspector を使用できます。

• npx @modelcontextprotocol/inspector で起動します
• Inspector 内で、Transport Type を SSE に切り替え、接続する MCP サーバーの URL として http://localhost:8787/sse を入力し、「Connect」をクリックします
• （モックの）ユーザー名／パスワードのログイン画面が表示されます。ログインするには任意のメールアドレスとパスワードを入力します
• MCP Inspector に戻り、定義済みのツールを一覧表示して呼び出せるようになります。

Workers AI Playground を使用する（Streamable HTTP）

最新の Streamable HTTP トランスポートプロトコルでテストするには、次の手順に従います。

1. Workers AI Playground にアクセスします
2. MCP サーバーへの接続を求められたら、エンドポイント URL を入力します。

   https://remote-mcp-server.robertjboulos.workers.dev/mcp
   

   ローカルでテストする場合は、次の URL を入力します。

   http://localhost:8787/mcp
   

3. 求められたら、認証情報を入力します。
   • auth_token：Xano 認証トークン
   • user_id：Xano ユーザー ID
4. Playground は、新しいプロトコルを使用してセッション管理を自動的に行います

ローカルの MCP サーバーに Claude Desktop を接続する

レガシー SSE トランスポート

古い SSE トランスポートを使用して接続するには、Anthropic のクイックスタートに従い、Claude Desktop で「Settings」>「Developer」>「Edit Config」の順に開いて設定ファイルを見つけます。

テキストエディターでファイルを開き、次の設定に置き換えます。

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

これによりローカルプロキシが起動し、Claude が HTTP 経由で MCP サーバーと通信できるようになります。

Streamable HTTP トランスポート（推奨）

より新しく効率的な Streamable HTTP トランスポートを Claude Desktop で使用するには、設定を更新して /mcp エンドポイントを使用します。

{
  "mcpServers": {
    "xano": {
      "remoteUrl": "http://localhost:8787/mcp",
      "auth": {
        "type": "bearer",
        "token": "YOUR_XANO_AUTH_TOKEN"
      },
      "headers": {
        "x-user-id": "YOUR_USER_ID"
      }
    }
  }
}

YOUR_XANO_AUTH_TOKEN と YOUR_USER_ID を実際の認証情報に置き換えます。

Claude を開くとブラウザーウィンドウが表示され、ログインできます。右下に利用可能なツールが表示されます。適切なプロンプトを入力すると、Claude がツールを呼び出すかどうか尋ねます。

Xano 統合

この MCP サーバーは、バックエンドとして Xano を使用します。

1. ツール管理：Xano の ____mcp_tools テーブルでツールを定義すると、MCP サーバーに自動的に登録されます
2. セッション追跡：すべての MCP セッションは、一意のセッション ID とともに ___mcp_sessions テーブルで追跡されます
3. OAuth 認証：OAuth トークンと状態は、Xano の ___oauth_tokens テーブルと ___oauth_states テーブルに保存されます
4. ログ記録：すべての MCP リクエストは ___mcp_logs テーブルに記録されます

Streamable HTTP の実装

このサーバーは、最新の Model Context Protocol Streamable HTTP トランスポート（2024-11-05）を次の機能とともに実装しています。

認証方法

サーバーは、幅広い互換性を実現するため、複数の認証方式に対応しています。

1. URL パラメーター：?auth_token=xxx&user_id=yyy（従来の方式）
2. Authorization ヘッダー：x-user-id ヘッダーとともに Authorization: Bearer xxx を指定する方式（最新の方式）
3. リクエストボディ：初期化ペイロードに認証パラメーターを含めることができます

セッション管理

サーバーは、最新の仕様に従ってセッション ID を処理します。

1. セッションの作成：新しい接続に対して、サーバーが一意のセッション ID を生成します
2. セッションの追跡：クライアントはこの ID を保存し、以降のリクエストに ?sessionId=xxx として含めます
3. 状態の永続化：各セッションは Xano 内で独自の状態を保持し、リクエストをまたいで維持されます

プロトコルへの準拠

この実装には、以下への適切な対応が含まれています。

1. 統合メッセージエンドポイント：/mcp/message エンドポイントのパターンに対応します
2. プロトコルヘッダー：すべてのレスポンスに MCP-Available-Transports などの適切なヘッダーが含まれます
3. SSE ストリーミング：ストリーミングレスポンス向けに SSE のサポートを強化しています
4. レスポンス形式：プロトコル固有の拡張機能を備えた標準の JSON-RPC 2.0 形式です

Xano のセットアップ

1. 必要なテーブルを含む Xano プロジェクトを作成します（データベーススキーマを参照）
2. 以下の API エンドポイントを作成します。
   • /api/tools - GET - すべてのツールを一覧表示します
   • /api/tools/execute/{tool_name} - POST - 特定のツールを実行します
   • /api/sessions - POST - 新しいセッションを作成します
   • /api/sessions/update-activity - PUT - セッションのアクティビティを更新します
   • /api/oauth/tokens - POST - OAuth トークンを保存します
   • /api/oauth/tokens/{user_id}/{provider} - GET - OAuth トークンを取得します
   • /api/oauth/states - POST - OAuth の状態を保存します
   • /api/oauth/states/{state} - GET - OAuth の状態を検証します
   • /api/logs - POST - MCP リクエストを記録します

Cloudflare へのデプロイ

1. npx wrangler kv namespace create OAUTH_KV
2. ガイダンスに従って、KV 名前空間 ID を wrangler.jsonc に追加します
3. Xano API キーを wrangler.jsonc の XANO_API_KEY 変数に追加します
4. npm run deploy

デプロイしたリモート MCP サーバーをリモート MCP クライアントから呼び出す

上記の「ローカルでの開発」と同様に、MCP Inspector を実行します。

npx @modelcontextprotocol/inspector@latest

次に、接続先の MCP サーバーの URL として、Worker の workers.dev URL（例：worker-name.account-name.workers.dev/sse）を Inspector に入力し、「Connect」をクリックします。

これで、リモート MCP クライアントから MCP サーバーに接続できました。

Claude Desktop をリモート MCP サーバーに接続する

Claude の設定ファイルを更新して workers.dev URL（例：worker-name.account-name.workers.dev/sse）を指定し、Claude を再起動します。

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://worker-name.account-name.workers.dev/sse"
      ]
    }
  }
}

デバッグ

問題が発生した場合は、Claude を再起動するか、次のコマンドを使ってコマンドラインから MCP サーバーに直接接続すると解決に役立つことがあります。

npx mcp-remote http://localhost:8787/sse

まれに、~/.mcp-auth に追加されたファイルを削除すると解決する場合があります。

rm -rf ~/.mcp-auth