MCPクライアントをPipesHub MCPサーバーに接続する

このガイドでは、PipesHubのリモートMCPサーバーをCursor、Claude Code、Gemini CLI、Codex CLI、Claude.ai（Web）、LibreChatに、静的OAuth認証情報またはベアラートークンを使用して接続する方法を説明します。

PipesHubは、Streamable HTTPを介して/mcpにリモートMCPエンドポイントを公開します。MCPクライアントはこのエンドポイントに直接接続します。ローカルのnpmパッケージやstdioプロセスは不要です。

コーディングエージェントですか？ コーディングエージェント向けから始めてください。npx skills add pipeshub-ai/mcp-serverでスキルをユーザーのリポジトリにインストールします（skills/pipeshubを参照）。このリポジトリのコントリビューターは、AGENTS.mdをお読みください。

ツールリファレンスをお探しですか？ TOOLS.mdで、MCPサーバーが公開する各ツール（pipeshub_chat、pipeshub_search、pipeshub_get_record_content、pipeshub_download_record、pipeshub_directory、pipeshub_sources、pipeshub_agents）の説明、引数、および判断ガイドを参照してください。

QMを使用していますか？ QMはサードパーティのMCPエンドポイントを接続できません。QMは独自のハーネスに対するMCPサーバーであり、クライアントではないためです。QMでPipesHubを使用するに従ってください。qm/内のデプロイメント層バンドルは、エージェントのサンドボックス内でpipeshubコマンドを提供します。このパッケージはそのコマンドを2番目のbinとして同梱しています。

前提条件

• 実行中のPipesHubインスタンス（セルフホストまたはクラウド）

• PipesHubで作成したOAuthアプリ（ステップ1を参照）

Related MCP server: Rocket.Chat MCP Server

ステップ1: PipesHubでOAuthアプリを作成する

1. 管理者としてPipesHubインスタンスにログインします

2. 設定 > 開発者設定 > OAuthアプリに移動します

3. OAuthアプリを作成をクリックします

4. アプリの詳細を入力します：

   • 名前：例：MCP Integration

   • リダイレクトURI：使用予定のクライアントのリダイレクトURIをすべて追加します：

     クライアント	リダイレクトURI
     Cursor	cursor://anysphere.cursor-mcp/oauth/callback
     Claude Code	http://localhost:<PORT>/callback（例：http://localhost:8080/callback）
     Claude.ai（Web）	https://claude.ai/api/mcp/auth_callback
     Gemini CLI	http://localhost:7777/oauth/callback
     LibreChat	http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

重要：MCP_SCOPESのスコープは、OAuthアプリに付与されたスコープと一致している必要があります。不一致があると認可エラーが発生します。

5. アプリを保存し、クライアントIDとクライアントシークレットをコピーします

デフォルトスコープのカスタマイズ

デフォルトでは、PipesHubは/.well-known/oauth-protected-resource/mcpディスカバリーエンドポイントでいくつかのデフォルトスコープを公開します。公開するスコープは、PipesHubインスタンスでMCP_SCOPES環境変数を設定することでカスタマイズできます。これは、公開されているすべてのスコープを自動的に要求するClaude Codeなどのクライアントに役立ちます。

プレースホルダー

以下のすべての設定で、これらを置き換えてください：

リモートMCPエンドポイントのURLは次のとおりです：PIPESHUB_INSTANCE_URL/mcp

リモートMCPのセットアップ

Cursorは、mcp.jsonのauthオブジェクトを介してリモートMCPサーバーの静的OAuthをサポートしています。

設定

Cursor設定 > ツールとインテグレーション > 新しいMCPサーバーを開くか、プロジェクトの.cursor/mcp.jsonを編集します：

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "auth": {
        "CLIENT_ID": "YOUR_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

Cursorは、PipesHubの/.well-known/oauth-protected-resource/mcpメタデータを介して認可エンドポイントとトークンエンドポイントを自動検出します。

注： scopesフィールドを省略すると、Cursorは/.well-known/oauth-protected-resource/mcpを取得し、そこにリストされているすべてのscopes_supportedを要求します。アクセスを制限するには、必要なスコープのみを明示的にリストしてください。サーバー側で公開するスコープを制御することもできます。デフォルトスコープのカスタマイズを参照してください。

環境変数の使用

Cursorの${env:VAR}補間を使用して、設定ファイルからシークレットを除外します：

{
  "mcpServers": {
    "pipeshub": {
      "url": "${env:PIPESHUB_INSTANCE_URL}/mcp",
      "auth": {
        "CLIENT_ID": "${env:PIPESHUB_CLIENT_ID}",
        "CLIENT_SECRET": "${env:PIPESHUB_CLIENT_SECRET}",
        "scopes": [
          "kb:read", "kb:write",
          "semantic:read", "semantic:write",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write",
          "config:read", "user:read"
        ]
      }
    }
  }
}

リダイレクトURI

Cursorは、すべてのMCPサーバーに対して固定のリダイレクトURIを使用します：

cursor://anysphere.cursor-mcp/oauth/callback

PipesHubでOAuthアプリを作成する際に、これを許可されたリダイレクトURIとして登録してください。

OAuthログインのトラブルシューティング

Cursorの内部ブラウザがOAuthログインページを読み込めない場合は、内部ブラウザから認可URLをコピーして通常のブラウザに貼り付け、ログインフローを完了してください。

Claude Codeは、--client-id、--client-secret、--callback-portを介して、静的OAuth認証情報を使用したリモートHTTP MCPサーバーをサポートしています。

PipesHubは/.well-known/oauth-protected-resource/mcpでディスカバリーを公開しているため、Claude Codeは認可エンドポイントとトークンエンドポイントを自動検出します。

重要： Claude Codeは特定のスコープの設定をサポートしていません。/.well-known/oauth-protected-resource/mcpを取得し、scopes_supportedリストを読み取り、すべてを要求します。PipesHubのOAuthアプリは、ディスカバリーエンドポイントにリストされているすべてのスコープにアクセスできる必要があります。そうしないと、認可リクエストは失敗します。公開するスコープを制限するには、デフォルトスコープのカスタマイズを参照してください。

CLIで追加

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

--client-secretを値なしで指定すると、マスクされた入力が求められます。プロンプトをスキップするには、MCP_CLIENT_SECRET環境変数を設定します：

MCP_CLIENT_SECRET=YOUR_CLIENT_SECRET claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

すべてのプロジェクトで使用できるようにするには：

claude mcp add --transport http --scope user \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

JSONで追加

claude mcp add-json pipeshub '{
  "type": "http",
  "url": "PIPESHUB_INSTANCE_URL/mcp",
  "oauth": {
    "clientId": "YOUR_CLIENT_ID",
    "callbackPort": 8080
  }
}' --client-secret

プロジェクトスコープ（.mcp.json）

プロジェクトのルートに.mcp.jsonファイルを作成します。これはバージョン管理にコミットできます（シークレットは環境変数で外部に保持されます）：

{
  "mcpServers": {
    "pipeshub": {
      "type": "http",
      "url": "${PIPESHUB_INSTANCE_URL}/mcp",
      "oauth": {
        "clientId": "${PIPESHUB_CLIENT_ID}",
        "callbackPort": 8080
      }
    }
  }
}

Claude Codeを起動する前に環境変数を設定します：

export PIPESHUB_INSTANCE_URL="https://app.pipeshub.com"
export PIPESHUB_CLIENT_ID="your-client-id"

注： クライアントシークレットは設定ファイルではなく、システムのキーチェーンに保存されます。/mcpで初めて認証する際に入力を求められます。

認証

サーバーを追加した後、Claude Code内で/mcpを実行し、ブラウザのログインフローに従います。トークンは安全に保存され、自動的に更新されます。

確認

claude mcp list
claude mcp get pipeshub

Gemini CLIは、dynamic_discovery（デフォルト）を介してOAuthを使用したリモートMCPサーバーをサポートしています。これは、PipesHubの/.well-known/oauth-protected-resource/mcpから認可エンドポイントとトークンエンドポイントを自動検出します。

オプションA：設定ファイル

~/.gemini/settings.jsonを編集します：

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "oauth": {
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

注： scopesリストを、OAuthアプリに付与されたスコープに合わせて調整してください。ツールのサブセットのみが必要な場合は、それに応じてスコープを制限できます。

オプションB：CLIコマンド

gemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp

次に、~/.gemini/settings.jsonを編集して、上記のようにoauthブロックを追加します。

認証

Gemini CLI内で、/mcp authコマンドを使用します：

# List servers and their auth status
/mcp auth

# Authenticate with PipesHub (opens browser for login)
/mcp auth pipeshub

# Re-authenticate if tokens expire
/mcp auth pipeshub

初回接続時に、Geminiは401レスポンスを自動的に検出し、OAuthエンドポイントを発見して、ログイン用のブラウザを開きます。トークンは~/.gemini/mcp-oauth-tokens.jsonに安全に保存され、自動的に更新されます。

サーバーの管理

# List all configured servers
gemini mcp list

# Remove the server
gemini mcp remove pipeshub

# Temporarily disable/enable
gemini mcp disable pipeshub
gemini mcp enable pipeshub

OAuth設定プロパティ

注： OAuthにはローカルブラウザが必要です。ヘッドレス環境、X11転送のないリモートSSH、ブラウザアクセスのないコンテナでは機能しません。

Codex CLI（OpenAI Codex）は、Streamable HTTPを介してリモートMCPサーバーに接続します。~/.codex/config.toml（またはプロジェクトルートの.codex/config.tomlでプロジェクト単位にスコープ）の[mcp_servers.<name>]テーブルで設定します。CodexのHTTPトランスポートは、環境変数から読み取られるベアラートークンで認証するため、PipesHubのJWTベアラートークンを渡します。

[mcp_servers.pipeshub]
url = "PIPESHUB_INSTANCE_URL/mcp"
bearer_token_env_var = "PIPESHUB_BEARER_TOKEN"

bearer_token_env_varは、トークンを保持する環境変数の名前です。Codexを起動する前にエクスポートします：

export PIPESHUB_BEARER_TOKEN="YOUR_BEARER_TOKEN"

トークンはBearerキーワードなしの生のJWTです。

または、CLIで追加します：

codex mcp add pipeshub \
  --url PIPESHUB_INSTANCE_URL/mcp \
  --bearer-token-env-var PIPESHUB_BEARER_TOKEN

--bearer-token-env-varは、トークン値そのものではなく、トークンを保持する環境変数の名前を受け取ります。

確認

# List configured MCP servers
codex mcp list

# Inside the Codex TUI, view server status and available tools
/mcp

Claude.aiは、リモートMCPサーバーを介したカスタムコネクタをサポートしています。これにより、ローカル設定なしでClaude.aiのWebインターフェースでPipesHubツールを直接使用できます。

注： この機能は現在ベータ版です。無料プランのユーザーはカスタムコネクタを1つに制限されています。

個人ユーザー向け（Pro / Maxプラン）

1. claude.aiにアクセスし、設定 > コネクタに移動します

2. コネクタセクションの下部にあるカスタムコネクタを追加をクリックします

3. MCPサーバーのURLを入力します：

   PIPESHUB_INSTANCE_URL/mcp

4. 詳細設定をクリックし、OAuth認証情報を入力します：

   • OAuthクライアントID：YOUR_CLIENT_ID

   • OAuthクライアントシークレット：YOUR_CLIENT_SECRET

5. 追加をクリックします

6. PipesHubのログインページにリダイレクトされ、認証と権限の付与を行います

7. 認証後、コネクタがアクティブになり、PipesHubツールがClaude.aiの会話で利用できるようになります

チーム / エンタープライズプラン向け

組織のオーナーが最初にコネクタを追加する必要があります：

1. 組織設定 > コネクタに移動します

2. カスタムコネクタを追加をクリックします

3. MCPサーバーのURLを入力します：PIPESHUB_INSTANCE_URL/mcp

4. 詳細設定をクリックし、OAuthクライアントIDとクライアントシークレットを入力します

5. 追加をクリックします

チームメンバーはその後接続できます：

1. 設定 > コネクタに移動します

2. PipesHubコネクタ（「カスタム」ラベル付き）を見つけます

3. 接続をクリックして、PipesHubのOAuthログインで認証します

リダイレクトURI

Claude.aiはOAuthに次のリダイレクトURIを使用します：

https://claude.ai/api/mcp/auth_callback

これをPipesHubのOAuthアプリで許可されたリダイレクトURIとして登録してください。

セキュリティに関する注意事項

• 信頼できるMCPサーバーにのみ接続してください

• OAuth認証フロー中に要求される権限を確認してください

• Claude.aiは付与されたOAuthトークンを使用してあなたの代わりにPipesHubとやり取りします。パスワードが共有されることはありません

LibreChatは、カスタムコネクタUIを介してOAuth認証を使用したリモートMCPサーバーをサポートしています。これにより、LibreChatインスタンスで利用可能な任意のモデルにPipesHubツールを接続できます。

設定

1. LibreChatインスタンスにログインします

2. MCP Servers設定パネルに移動します

3. Addをクリックして新しいカスタムMCPコネクタを作成します

4. コネクタの詳細を入力します：

   • Name：Pipeshub（または任意の名前）

   • MCP Server URL：PIPESHUB_INSTANCE_URL/mcp

   • Transport：Streamable HTTPSを選択

   • Authentication：OAuthを選択

5. OAuth認証情報を入力します：

   • Client ID：YOUR_CLIENT_ID

   • Client Secret：YOUR_CLIENT_SECRET

   • Authorization URL：PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

   • Token URL：PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

   • Scope：openid email（または必要に応じて追加のスコープ）

6. I trust this applicationにチェックを入れます

7. Addをクリックしてコネクタを保存します

8. 追加後、LibreChatはコネクタ設定パネル（コピーボタンの横）にRedirect URIを生成して表示します。形式は次のとおりです：

   http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

9. Redirect URIをコピーし、PipesHub OAuthアプリの許可されたリダイレクトURIとして登録します（ステップ1を参照）

10. LibreChatのコネクタに戻り、UpdateをクリックしてOAuthフローを開始します — PipesHubのログインページにリダイレクトされ、認証と権限の付与を行います

Redirect URI

LibreChatはコネクタ作成後にリダイレクトURIを生成します。URIの形式は次のとおりです：

http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

<server-identifier>はLibreChatが割り当てる一意の識別子です（コネクタ設定の上部に「Unique Server Identifier」として表示されます）。このURIをコピーし、認証前にPipesHub OAuthアプリの許可されたリダイレクトURIに追加する必要があります。

注： LibreChatインスタンスが別のホストやポートで実行されている場合、URIはそれを反映します（例：https://chat.example.com/api/mcp/pipeshub/oauth/callback）。

Scopes

LibreChatでは、ScopeフィールドでOAuthスコープを指定できます。スペース区切りのリストを使用します：

openid email

PipesHub固有のスコープを要求するには、スコープフィールドに追加します：

openid email org:read kb:read kb:write semantic:read conversation:read conversation:write conversation:chat agent:read agent:execute

注： 要求するスコープは、PipesHubでOAuthアプリに付与されたスコープと一致している必要があります。詳細はデフォルトスコープのカスタマイズを参照してください。

ローカルMCPサーバー（Stdio）

PipesHubのリモートMCPエンドポイントに接続する代わりに、@pipeshub-ai/mcp npmパッケージを使用してMCPサーバーをローカルのstdioプロセスとして実行できます。これは、ローカルセットアップを好む場合や、リモートMCPエンドポイントへの直接HTTP接続が現実的でない環境で作業する必要がある場合に便利です。

前提条件

• Node.js 18以上がインストールされていること

• PipesHubインスタンスのURL

• 認証情報：Bearerトークン（JWT）またはOAuth Client ID + Secret

プレースホルダー

以下のすべての設定で、これらを置き換えてください：

Claude Desktopの設定（claude_desktop_config.json）で構成します：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

OAuth認証情報を使用する場合：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

Cursor Settings > Tools and Integrations > New MCP Serverを開くか、プロジェクトの.cursor/mcp.jsonを編集します：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

OAuth認証情報を使用する場合：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

OAuth認証情報を使用する場合：

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

OAuth認証情報を使用する場合：

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

MCPサーバーをローカルのstdioプロセスとして実行し、OAuthアプリのClient IDとSecret（client_credentialsグラント）で認証します。~/.codex/config.toml（またはプロジェクトルートの.codex/config.toml）を編集します：

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL/api/v1",
  "--client-id",
  "YOUR_CLIENT_ID",
  "--client-secret",
  "YOUR_CLIENT_SECRET",
  "--token-url",
  "/api/v1/oauth2/token",
]

注意：

• --server-urlには/api/v1を含める必要があります。

• --token-url /api/v1/oauth2/tokenが必要です。

または、代わりにJWT Bearerトークンで認証します：

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL/api/v1",
  "--bearer-auth",
  "YOUR_BEARER_TOKEN",
]

コマンドパレット > MCP: Open User Configurationを開き、次を追加します：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Windsurf Settings > Cascade > Manage MCPs > View raw configを開き、次を追加します：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

npmパッケージの代わりにクローンしたリポジトリからローカルMCPサーバーを実行する場合：

git clone https://github.com/pipeshub-ai/pipeshub-ai.git
cd pipeshub-ai
npm install
npm run build
node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

MCPクライアント設定では、npx @pipeshub-ai/mcpをnode ./bin/mcp-server.jsに置き換えます：

{
  "mcpServers": {
    "pipeshub": {
      "command": "node",
      "args": [
        "./bin/mcp-server.js",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

MCP Inspectorでデバッグする場合：

npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

CLIヘルプ

サーバー引数の完全なリスト：

npx @pipeshub-ai/mcp --help

動作の仕組み

アーキテクチャ

AI Client (Cursor / Claude Code / Gemini CLI / Codex CLI / Claude.ai / LibreChat)
        │
        │  HTTP POST (JSON-RPC)
        │  Authorization: Bearer <token>
        ▼
  PIPESHUB_INSTANCE_URL/mcp
        │
        │  StreamableHTTP Transport
        │  (stateless, per-request MCP server)
        ▼
  PipesHub API (curated tool set — see TOOLS.md)

OAuth保護リソースのディスカバリー

PipesHubは、次の場所でOAuth保護リソースのディスカバリーを公開しています：

PIPESHUB_INSTANCE_URL/.well-known/oauth-protected-resource/mcp

これにより、すべてのOAuthエンドポイントが自動的に返されます：

• 認可：PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

• トークン：PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

• 失効：PIPESHUB_INSTANCE_URL/api/v1/oauth2/revoke

• JWKS：PIPESHUB_INSTANCE_URL/.well-known/jwks.json

トラブルシューティング

「Incompatible auth server: does not support dynamic client registration」

これは、クライアントが事前設定された認証情報を使用する代わりに動的登録を試みていることを意味します。--client-idと--client-secret（Claude Code）またはauthオブジェクト（Cursor）を正しく渡したことを確認してください。

認証失敗 / リダイレクトエラー

• OAuthアプリのRedirect URIがクライアントが使用するものと完全に一致していることを確認してください：

  • Cursor：cursor://anysphere.cursor-mcp/oauth/callback

  • Claude Code：http://localhost:<callbackPort>/callback

  • Claude.ai：https://claude.ai/api/mcp/auth_callback

  • Gemini CLI：http://localhost:7777/oauth/callback

  • LibreChat：http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

• OAuthアプリがPipesHubでアクティブ（停止されていない）であることを確認してください

MCPエンドポイントに到達できない

• エンドポイントにアクセスできることを確認します：curl -X POST PIPESHUB_INSTANCE_URL/mcp（接続エラーではなく401が返されるはずです）

• PipesHubインスタンスでMCPが有効になっていることを確認します

MCP Inspectorでのデバッグ

npx @modelcontextprotocol/inspector

次に、Bearerトークンを使用してPIPESHUB_INSTANCE_URL/mcpに接続し、エンドポイントを直接テストします。

FAQ

1. PipesHubインスタンスのMCP_SCOPES環境変数を更新して、ディスカバリーエンドポイント経由で公開する新しいスコープを含めます。

2. PipesHubでOAuthアプリのスコープを更新します：Settings > Developer Settings > OAuth Appsに移動し、OAuthアプリを選択して、必要に応じてスコープを追加または削除します。

3. クライアントを再認証します — 既存のトークンには古いスコープが含まれているため、更新されたスコープで新しいトークンを取得するには再認証が必要です。例：

   • Cursor：MCPサーバーを削除して再追加するか、キャッシュされたOAuthトークンをクリアして再接続します。

   • Claude Code：/mcpを実行し、ブラウザのログインフローを再度完了します。

   • Gemini CLI：/mcp auth pipeshubを実行して再認証します。

   • Codex CLI：PIPESHUB_BEARER_TOKENを新しいトークンで更新し、Codexを再起動します。

   • Claude.ai：Settings > Connectorsでコネクタを切断して再接続します。