outsystems-mcp-relay

경량의 범용 stdio → 원격 MCP 릴레이로, OAuth를 지원하며, 게시된 OAuth 메타데이터가 인증 응답과 일치하지 않는 원격 서버를 위한 RFC 9207 발급자(issuer) 재정의 기능을 포함합니다. 런타임 의존성 없음. 단일 파일.

stdio (your MCP client)  ⇄  outsystems-mcp-relay  ⇄  remote MCP server (Streamable HTTP)

왜 존재하는가

일부 원격 MCP 배포는 Keycloak 앞의 리버스 프록시입니다(예: OutSystems Developer Cloud MCP 게이트웨이). 이들은 issuer가 프록시 URL(예: https://<tenant>/mcp)인 OAuth 메타데이터를 게시하지만, 인증 서버는 인증 응답의 iss 매개변수에 실제 발급자(예: https://<tenant>/auth/realms/<realm>)를 표시합니다.

RFC 9207을 준수하는 클라이언트는 반드시 이 불일치를 거부해야 하므로, 모든 하네스(Claude Code, pi, Cursor, Codex 등)에서 OAuth 로그인이 실패합니다. 이 릴레이는 다른 모든 OAuth 검사를 엄격하게 유지하면서 iss를 실제 백엔드 발급자에 대해 검증할 수 있게 해줍니다. 일반 서버에서는 평범한 릴레이처럼 동작합니다.

Related MCP server: mcp-auth-proxy

언제 사용하나

공식 직접 연결을 먼저 시도하세요. 하네스를 원격 MCP URL에 바로 연결하고, 릴레이를 거치지 마세요. 위의 RFC 9207 발급자 불일치 오류로 실패할 때만 이 릴레이를 사용하세요.

이 릴레이는 하나의 서버 측 버그를 우회하기 위해서만 존재합니다. 버그가 없으면 공식 경로보다 나은 점이 없습니다. 따라서 OutSystems에서 테넌트 전체에서 수정하거나, 테넌트가 처음부터 이 문제를 겪지 않았다면, 릴레이를 버리고 직접 연결하세요. 릴레이는 그런 경우를 알려줍니다. 로그인 성공 시 발급자 수정이 실제로 필요했는지 확인하고, 필요하지 않았다면 stderr에 그 사실을 알리는 메시지를 출력합니다. "아직 필요한가" 검토를 기다리지 마세요. 그 메시지가 보이면 즉시 공식 직접 연결로 전환하세요.

설치

Node.js ≥ 20이 필요합니다. 의존성 없음 — 파일만 있으면 됩니다.

npm install -g outsystems-mcp-relay      # recommended
# or, without a global install:
npx outsystems-mcp-relay <remote-url> ...

릴레이를 사용하려면 이 저장소를 클론할 필요가 없습니다. npm에서 설치(또는 npx 사용)하면 끝입니다. 소스(약 500줄짜리 단일 파일)를 감사하거나 기여할 때만 클론하세요.

사용법

outsystems-mcp-relay <remote-url> [options]

  --as-metadata-url <url>   OAuth AS metadata URL (default: discover from remote-url)
  --expected-issuer <url>   Override the RFC 9207 expected issuer (the proxy fix)
  --client-id <id>          Pre-registered client id (skips dynamic registration)
  --bearer <token>          Static bearer token mode (skips OAuth entirely)
  --force                   Ignore cached tokens and re-authenticate
  --no-open                 Print the authorization URL instead of opening a browser
  --help                    Show help

일반 예시(일반 원격 서버)

// mcp.json
{
  "mcpServers": {
    "my-remote": {
      "command": "outsystems-mcp-relay",
      "args": ["https://api.example.com/mcp"]
    }
  }
}

OutSystems 예시(발급자 불일치)

{
  "mcpServers": {
    "outsystems": {
      "command": "outsystems-mcp-relay",
      "args": ["https://<tenant>.outsystems.dev/mcp"]
    }
  }
}

--expected-issuer는 필요 없습니다. 릴레이는 인증 리다이렉트(Keycloak realm 설정)에서 실제 인증 서버 발급자를 자동 감지합니다. 자동 감지가 실패하는 경우(Keycloak이 아닌 서버)에만 --expected-issuer https://<tenant>.outsystems.dev/auth/realms/<realm-id>를 추가하세요. OAuth 오류 메시지에 realm이 출력됩니다. 그 received 값이 사용할 값입니다. 자동 감지는 교차 출처 후보가 해당 realm의 자체 메타데이터(출처 허용 목록을 통해 도달 가능)로 발급자가 확인된 경우에만 채택합니다. 진정으로 분리된 IdP 호스트라면 --expected-issuer(또는 사전 허용 목록을 위한 --as-metadata-url)를 전달하세요.

첫 호출 시 릴레이는 로그인을 위해 브라우저를 엽니다(또는 --no-open으로 URL을 출력합니다). 토큰은 캐시되고 자동으로 갱신됩니다.

AI 어시스턴트로 설치(붙여넣기)

Claude Code, pi, Cursor 또는 모든 AI 하네스에 붙여넣으세요:

Install the OutSystems MCP fix (outsystems-mcp-relay). The official OutSystems
MCP fails OAuth on every AI harness with an RFC 9207 issuer mismatch — a
server-side bug in the gateway's Keycloak setup.
Step 1: run `npm install -g outsystems-mcp-relay`.
Step 2: ask me for my OutSystems tenant hostname (something like
`mycompany.outsystems.dev`).
Step 3: when I tell you, replace the broken server:
  `claude mcp remove outsystems`
  `claude mcp add -s user --transport stdio outsystems -- outsystems-mcp-relay https://<my-tenant>/mcp`
  (substitute my actual tenant. No other flags needed — the relay auto-detects
  the real authorization-server issuer; if auto-detection can't, ask me to paste
  the OAuth error and use its "received" URL as `--expected-issuer`.)
Step 4: tell me to restart Claude Code, then ask anything OutSystems-related.
The first tool call opens a browser for sign-in (or prints the URL with
`--no-open`).

Claude Code 빠른 시작(OutSystems 발급자 불일치)

보고 있는 오류는 다음과 같습니다:

Issuer mismatch in authorization response (RFC 9207):
expected "https://<tenant>.outsystems.dev/mcp",
received "https://<tenant>.outsystems.dev/auth/realms/<realm-id>"

터미널에서(Claude Code 내부가 아닌):

npm install -g outsystems-mcp-relay

# 1. remove the broken HTTP entry
claude mcp remove outsystems

# 2. add the relay as a local stdio server — no other flags needed: it
#    auto-detects the real authorization-server issuer
claude mcp add -s user --transport stdio outsystems -- \
  outsystems-mcp-relay \
  https://<tenant>.outsystems.dev/mcp

그런 다음 Claude Code를 다시 시작하세요. 첫 OutSystems 도구 호출 시 릴레이는 로그인을 위해 브라우저를 엽니다(URL을 붙여넣고 싶다면 --no-open을 추가하세요). 토큰이 캐시되므로 이후 세션에서는 로그인을 건너뜁니다. /mcp(서버가 연결되어 있어야 함)와 간단한 "내 환경 목록"으로 확인하세요.

realm 발급자를 찾을 필요가 없습니다. 릴레이는 인증 리다이렉트에서 자동 감지합니다. 자동 감지가 불가능한 경우(Keycloak이 아닌 서버) 오류 메시지에 출력됩니다. 오류의 received 값이 바로 --expected-issuer 값입니다.

작동 방식

• 프로토콜 무관 통과(passthrough): stdin에서 개행으로 구분된 JSON-RPC를 읽고 각 프레임을 원격 서버에 그대로 POST한 후 JSON-RPC 응답을 stdout에 씁니다. 도구 의미론은 없습니다. 도구, 리소스, 프롬프트 등 무엇이든 동작합니다.

• Streamable HTTP 세부 사항 처리: Mcp-Session-Id 에코, 직접 JSON 응답, 202/text/event-stream 응답(SSE 재조립).

• OAuth: 인증 서버 메타데이터를 발견하고, 공개 클라이언트(PKCE S256)를 동적으로 등록하며, 브라우저를 열고, state와 iss를 검증하고, 코드를 교환하고, 401에서 토큰을 갱신합니다. --expected-issuer는 iss가 검증되는 발급자를 설정합니다 — 프록시/Keycloak 불일치에 대한 수정입니다.

• 요청은 직렬화됩니다(stdout에 응답이 섞이지 않음).

보안

• RFC 9207 적용: iss는 인증 서버가 실제로 보낼 때만 검증됩니다(없으면 = AS가 RFC 9207을 구현하지 않음, 검사 없음; 있으면 = 예상 발급자와 엄격한 문자열 일치). --expected-issuer는 다른 expected value를 선택하는 것입니다 — 검증을 비활성화하지 않습니다.

• 출처 허용 목록: 릴레이는 구성된 원격 출처(및 명시적으로 제공된 --as-metadata-url)에만 접촉합니다. 리다이렉트는 수동으로 처리되며 모든 홉이 허용 목록에 포함됩니다(307/308은 요청 본문을 유지; 301/302/303은 HTTP 의미론에 따라 GET으로 다운그레이드). 리다이렉트가 출처를 바꾸면 Authorization/Cookie는 제거됩니다(네이티브 fetch와 일치). SSRF 없음.

• PKCE S256 + 임의 state(검증됨) + 임시 포트의 localhost 전용 콜백 서버.

• 비밀 정보를 로그에 남기지 않음: 토큰과 인증 코드는 출력에 절대 나타나지 않습니다(모든 진단은 stderr로; stdout은 프로토콜 메시지만 전달).

• 토큰은 ~/.mcp-auth/outsystems-mcp-relay-<sha1(url)>.json에 0600 권한으로 저장됩니다 — 생태계 관례(mcp-remote와 동일한 저장소 형태). OS 키체인 저장은 계획된 개선 기능입니다. Non-goals 참고.

테스트

npm test                # mock-server protocol test (passthrough, session-id, SSE, 401)
npm run test:e2e -- <remote-url> --expected-issuer <issuer>   # real-tenant round trip

문제 해결

비목표(v1)

• OS 키체인 토큰 저장(현재는 0600 권한 파일)

• 다중 서버 집계/관리(게이트웨이 사용)

• 통과(passthrough)를 넘어서는 서버 시작 알림 스트리밍

• 사용자 지정 CA 플래그

라이선스

MIT