cosense-mcp-worker

A stateless Remote MCP server that operates on a single Cosense (formerly Scrapbox) project. It runs on Cloudflare Workers, using Hono for HTTP routing and Cloudflare Agents' createMcpHandler() with MCP SDK v2 for MCP. The Worker does not implement OAuth itself; that is delegated to Cloudflare Access Managed OAuth.

One Worker is fixed to one Cosense project and one connect.sid. Other projects or credentials cannot be specified or changed from MCP tool arguments.

One-click deploy to Cloudflare

From this button, users can create, build, and deploy a Worker to their own Cloudflare account. On the setup screen, enter the Worker name, COSENSE_PROJECT_NAME, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD, and the Secret COSENSE_SID.

After deployment, users must create the Cloudflare Access Application, enable Managed OAuth, and configure the Access Policy themselves.

Provided endpoints

MCP tools

Local setup

What you need: Node.js 20 or later, Corepack, a Cloudflare account that can use Cloudflare Zero Trust, and a session ID with permissions for the target Cosense project.

git clone <リポジトリURL> cosense-mcp-worker
cd cosense-mcp-worker
corepack enable
pnpm install

Set non-secret values in wrangler.jsonc.

"vars": {
  "COSENSE_PROJECT_NAME": "your-project",
  "CF_ACCESS_TEAM_DOMAIN": "https://your-team.cloudflareaccess.com",
  "CF_ACCESS_AUD": "YOUR_ACCESS_APPLICATION_AUDIENCE_TAG"
}

Always set the session ID as a Worker Secret. Do not save it in wrangler.jsonc, source code, or Git.

pnpm wrangler secret put COSENSE_SID

For local development only, set it in .dev.vars, which is not committed.

COSENSE_SID=your-connect.sid-value

Verification and local execution are as follows.

pnpm lint
pnpm typecheck
pnpm test
pnpm wrangler dev --local

Cloudflare Access Managed OAuth settings

Only when you are ready to deploy, run the following command.

pnpm deploy

Next, in the Cloudflare Zero Trust dashboard, create an Access Application for the Worker's hostname.

1. Create an MCP server application targeting the Worker's domain and the /mcp path.

2. Configure an Access Policy with users or ID groups allowed to use the target Cosense project.

3. Copy the Application Audience (AUD) Tag and set it in CF_ACCESS_AUD.

4. Confirm that the Zero Trust Team Domain matches CF_ACCESS_TEAM_DOMAIN.

5. Enable Managed OAuth in the Application's Advanced settings.

6. Register https://<worker-host>/mcp with the MCP client.

Cloudflare Access handles the Authorization Code Flow, PKCE, login, refresh tokens, OAuth discovery, and Access Policy. The Worker itself does not implement an OAuth server.

The Worker receives Cf-Access-Jwt-Assertion and only passes requests to /mcp to the MCP handler after verifying the RS256 signature, issuer, and AUD using the Team's JWKS endpoint.

When using Managed OAuth, OAuth discovery information is returned to the client from the Access layer. Do not add OAuth endpoints or a custom authorization server inside the Worker.

Security properties

• Treat COSENSE_SID as a Secret binding and do not include it in JSON responses or logs.

• /mcp rejects requests with a missing or invalid Access assertion with 401.

• The Access JWT signature is verified at https://<team-domain>/cdn-cgi/access/certs, and the issuer and AUD are also verified.

• /mcp allows all Origins. Compatibility with Remote MCP clients is prioritized; access control is performed by Cloudflare Access OAuth tokens and JWT validation inside the Worker.

• Because MCP tool schemas reject undefined inputs, callers cannot override projects or credentials.

• Arbitrary error details from Cosense are not returned as-is; errors are limited to operation-level errors.

• To avoid unintentionally returning huge responses, tool output is capped at 100,000 characters.

Directory structure

src/
  config.ts                 Worker bindingの検証
  index.ts                  Honoルートとstateless MCP HTTP transport
  middleware/access-auth.ts Access JWTの検証
  mcp/server.ts             MCP SDK v2 server factory
  mcp/tools/                ツールごとのスキーマと登録処理
  cosense/client.ts         Cosense adapter
  cosense/formatter.ts      LLM向けページ整形
  cosense/insert-lines.ts   純粋な挿入位置計算
test/                       外部Cosense APIを呼ばないユニットテスト

References

• Cloudflare Agents MCP handler APIs

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Cosense API Help

Inspired by yosider/cosense-mcp-server. This project does not copy code from that repository; it is a new implementation for Cloudflare Workers.