PipesHub MCP 서버에 MCP 클라이언트 연결하기

이 가이드에서는 정적 OAuth 자격 증명 또는 Bearer 토큰을 사용하여 PipesHub의 원격 MCP 서버를 Cursor, Claude Code, Gemini CLI, Codex CLI, Claude.ai (Web) 및 LibreChat에 연결하는 방법을 설명합니다.

PipesHub는 /mcp에서 Streamable HTTP를 통해 원격 MCP 엔드포인트를 노출합니다. MCP 클라이언트는 이 엔드포인트에 직접 연결합니다. 로컬 npm 패키지나 stdio 프로세스가 필요 없습니다.

코딩 에이전트인가요? 코딩 에이전트용에서 시작하세요. npx skills add pipeshub-ai/mcp-server 명령으로 스킬을 사용자의 저장소에 설치하세요(skills/pipeshub 참조). 이 저장소에서 작업하는 기여자라면 AGENTS.md를 읽으세요.

도구 참조를 찾고 계신가요? MCP 서버가 노출하는 각 도구(pipeshub_chat, pipeshub_search, pipeshub_get_record_content, pipeshub_download_record, pipeshub_directory, pipeshub_sources, pipeshub_agents)에 대한 설명, 인수, 결정 가이드는 TOOLS.md를 참조하세요.

QM을 사용 중인가요? QM은 타사 MCP 엔드포인트를 연결할 수 없습니다. QM은 자체 하네스에 대한 MCP 서버이지 클라이언트가 아닙니다. QM과 함께 PipesHub 사용하기를 따르세요. qm/의 배포 계층 번들은 에이전트의 샌드박스 내에 pipeshub 명령을 제공합니다. 이 패키지는 해당 명령을 두 번째 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. 앱을 저장하고 Client ID와 Client Secret을 복사합니다.

기본 스코프 사용자 지정

기본적으로 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를 허용된 리디렉션 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 전송은 환경 변수에서 읽은 Bearer 토큰으로 인증하므로 PipesHub JWT Bearer 토큰을 전달하세요.

[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 웹 인터페이스에서 PipesHub 도구를 직접 사용할 수 있습니다.

참고: 이 기능은 현재 베타 버전입니다. 무료 요금제 사용자는 사용자 지정 커넥터를 하나만 사용할 수 있습니다.

개인 사용자(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 커넥터("Custom" 레이블이 표시됨)를 찾습니다.

3. 연결을 클릭하여 PipesHub의 OAuth 로그인으로 인증합니다.

리디렉션 URI

Claude.ai는 OAuth에 다음 리디렉션 URI를 사용합니다:

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

PipesHub OAuth 앱에서 이 URI를 허용된 리디렉션 URI로 등록하세요.

보안 참고 사항

• 신뢰할 수 있는 MCP 서버에만 연결하세요.

• OAuth 인증 흐름 중에 요청되는 권한을 검토하세요.

• Claude.ai는 부여된 OAuth 토큰을 사용하여 사용자를 대신해 PipesHub와 상호작용합니다. 비밀번호가 공유되는 일은 없습니다.

LibreChat은 사용자 지정 커넥터 UI를 통해 OAuth 인증으로 원격 MCP 서버를 지원합니다. 이를 통해 PipesHub 도구를 LibreChat 인스턴스에서 사용 가능한 모든 모델에 연결할 수 있습니다.

구성

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

Placeholders

아래 모든 구성에서 다음을 바꾸세요:

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 엔드포인트를 자동으로 반환합니다:

• Authorization: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

• Token: PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

• Revocation: 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가 클라이언트가 사용하는 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에서 커넥터를 연결 해제하고 다시 연결합니다.