random-mcp

Cloudflare Workers에서 동작하는 난수 생성용 MCP(Model Context Protocol) 서버입니다. Notion Agent 등의 MCP 클라이언트에서 정수, 부동소수점 수, 가중치 선택, 다양한 확률 분포의 표본을 생성할 수 있습니다.

목적

언어 모델 자체가 난수를 선택하지 않고, 외부의 난수 생성 처리를 MCP 도구로 호출할 수 있게 하는 것을 목적으로 합니다.

언어 모델에 난수 선택을 맡기면 모델의 학습 데이터나 출력 경향이 결과에 영향을 미쳐 통계적으로 편향된 값이 생성됩니다. 예를 들어 "1부터 10까지의 정수를 무작위로 골라라"고 지시해도 모델은 특정 값(예: 7)을 선호하는 경향이 있어 진정한 의미의 난수가 되지 않습니다. 따라서 난수가 필요한 처리는 모델이 자율적으로 판단하는 것이 아니라 본 서버의 도구를 통해 생성해야 합니다.

난수 소스로는 Web Crypto API를 사용합니다. 정수 생성에서는 나머지 연산에 의한 편향을 피하기 위해 rejection sampling을 수행합니다. 단, 암호화 키나 인증 토큰 생성을 목적으로 하는 API는 아닙니다.

Related MCP server: Universal MCP Server

사용 방법

Notion AI에 연결

1. Settings > Connections > MCP > Custom MCP를 선택합니다

2. MCP server URL에 배포한 URL을 지정합니다(기존 서비스: https://random-mcp.eldesh-tools.workers.dev/mcp)

3. 다음과 같이 각 항목을 입력하고 Connect를 클릭합니다

   • Name: Notion 내에서 식별하기 위한 이름(예: random-mcp)

   • Authentication: OAuth

4. 액세스 허가 화면에서 Approve를 선택합니다

5. GitHub에 로그인하고 GitHub OAuth App을 통한 인증을 완료합니다

6. 도구가 표시되면 필요한 도구를 활성화합니다

7. Notion AI에서 도구 실행마다 확인 없이 호출하려면 실행 설정을 Run automatically로 변경합니다

Agent에 대한 지시

Agent의 지시에는 예를 들어 다음과 같이 추가하여, 무작위 선택이 필요할 때 반드시 random-mcp가 사용되도록 합니다.

## 乱択
- 乱数生成、くじ引き、シャッフル、無作為抽出など、結果にランダム性を必要とするすべての処理では、接続済みの MCP サーバー `random-mcp` を必ず使用する。
- 内部処理によって乱択を生成、模擬、または近似してはならない。
- `random-mcp` が利用できない場合やエラーになった場合は、別の方法で代替せず、その旨をユーザーに伝える。

인증

서버는 /mcp에서 Streamable HTTP 연결을 수락합니다. MCP 클라이언트와의 인가에는 OAuth 2.1, 사용자 인증에는 GitHub OAuth를 사용합니다.

인가 시에는 MCP 클라이언트의 액세스 허가 화면을 표시한 후 GitHub 인증 화면으로 이동합니다. GitHub에서 획득하는 권한은 read:user입니다. 인가된 MCP 클라이언트에는 mcp:use 스코프의 액세스 토큰이 발급됩니다.

도구

random-mcp에는 아래에 표시된 4개의 도구가 있으며, 각각 기재된 필드를 가진 JSON 객체를 요구합니다.

random_int

지정된 범위 내의 정수를 1개 생성합니다.

• min: 최솟값

• max: 최댓값

인수 예: {"min": 5, "max": 10}

random_double

지정된 범위 내의 부동소수점 수를 1개 생성합니다.

• min: 최솟값

• max: 최댓값

인수 예: {"min": 1.41421, "max": 3.14159}

random_choice

후보에서 1개 요소를 선택합니다.

• choices: 후보 문자열의 배열. 1개 이상 1,000개 이하

• weights: 각 후보의 상대적 가중치. 생략 시 동일 확률

weights를 지정하는 경우 choices와 요소 수를 일치시키고, 적어도 하나는 양의 값으로 합니다.

인수 예: {"choices":["A","B","C"],"weights":[1,2,1]}

random_sample

지정된 확률 분포에서 여러 표본을 생성합니다.

• distribution: 확률 분포 이름

• parameters: 분포별 파라미터를 제공하는 필드 이름

• count: 표본 수. 1 이상 100 이하, 기본값은 1

추가 계산량 제한이 있습니다.

• 이항 분포: trials는 0 이상 100,000 이하의 안전한 정수이며, trials * count <= 100000

• 푸아송 분포: lambda는 0 이상 100 이하이며, lambda * count <= 10000

인수 예: {"distribution":"uniform","parameters":{"min":5,"max":15},"count":3}

개발 환경

• Node.js 22.19.0 이상

• npm

• GitHub 계정

• Cloudflare 계정(배포하는 경우)

의존 관계를 설치합니다.

npm install

로컬 개발

GitHub OAuth App 생성

GitHub의 Developer settings에서 OAuth App을 생성합니다. 로컬 환경과 프로덕션 환경은 콜백 URL이 다르므로 각각 별도의 OAuth App을 생성합니다.

로컬 개발용 OAuth App에는 다음 값을 설정합니다.

• Homepage URL: http://localhost:8787

• Authorization callback URL: http://localhost:8787/callback

프로덕션용 OAuth App에서는 http://localhost:8787 부분을 배포 대상 Worker의 오리진으로 바꿉니다. 기존 서비스의 콜백 URL은 https://random-mcp.eldesh-tools.workers.dev/callback입니다.

생성 후 Client ID와 Client secret을 획득합니다. 이 애플리케이션이 GitHub에 요구하는 OAuth 스코프는 read:user입니다.

환경 변수

프로젝트 바로 아래에 .dev.vars를 생성합니다.

GITHUB_CLIENT_ID=<GitHub OAuth App の Client ID>
GITHUB_CLIENT_SECRET=<GitHub OAuth App の Client secret>
COOKIE_ENCRYPTION_KEY=<Cookie の暗号化に使用するランダムな値>

COOKIE_ENCRYPTION_KEY는 예를 들어 다음 명령으로 생성할 수 있습니다.

openssl rand -hex 32

OAuth의 임시 state는 wrangler.jsonc의 OAUTH_KV 바인딩에서 지정한 Cloudflare KV에 저장됩니다. 다른 Cloudflare 계정에 배포하는 경우 KV namespace를 생성하고 wrangler.jsonc의 id를 해당 namespace ID로 바꿔주세요.

시작

로컬 서버를 시작합니다.

npm run dev

일반적으로 MCP 엔드포인트는 다음 URL이 됩니다.

http://localhost:8787/mcp

[!NOTE] Wrangler가 Request.cf를 가져올 수 없다는 경고를 표시해도 마지막에 Ready on http://localhost:8787이 표시되고, 이 프로젝트가 Request.cf를 사용하지 않는다면 동작 확인을 계속할 수 있습니다.

MCP Inspector로 동작 확인

로컬 서버를 시작한 상태에서 MCP Inspector의 Web UI를 시작합니다.

npx --yes @modelcontextprotocol/inspector@latest

Inspector에서 Streamable HTTP를 선택하고 연결 대상에 http://localhost:8787/mcp를 지정합니다. 연결 시 브라우저에서 OAuth 인가 흐름이 시작되므로 액세스를 허용하고 GitHub 인증을 완료합니다. 프로덕션 환경을 확인하는 경우 연결 대상을 배포된 MCP URL로 변경합니다.

연결 후 Tools 화면에 도구에 표시된 것들이 표시되는지 확인합니다.

Cloudflare Workers에 배포

Cloudflare에 로그인합니다.

npx wrangler login

프로덕션용 GitHub OAuth App의 인증 정보와 Cookie 암호화 키를 Cloudflare Secret으로 등록합니다.

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY

GitHub OAuth App의 Authorization callback URL이 배포 대상 Worker의 /callback을 가리키는지, wrangler.jsonc의 OAUTH_KV가 사용 가능한 KV namespace를 가리키는지 확인합니다.

배포합니다.

npm run deploy

공개 URL은 일반적으로 다음 형식입니다.

https://random-mcp.<subdomain>.workers.dev/mcp

[!IMPORTANT] .dev.vars는 Cloudflare에 자동으로 반영되지 않습니다. 프로덕션 Worker는 Cloudflare Secret에 등록한 값을 참조합니다.

라이선스

MIT License 하에 공개하고 있습니다.