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. OAuth implementation is not held in the Worker; it is delegated to Cloudflare Access Managed OAuth.

One Worker is fixed to one Cosense project and one connect.sid. MCP tool arguments cannot specify or change a different project or credentials.

How to use from various MCP clients

• Name Cosense

• MCP endpoint https://<worker-host>/mcp

• Authentication OAuth

Related MCP server: Remote MCP Server with Bearer Auth

One-click deploy to Cloudflare

From this button, you can create, build, and deploy a Worker to your 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.

Creating the Cloudflare Access Application, enabling Managed OAuth, and configuring the Access Policy must be done by the user after deployment.

Provided endpoints

MCP tools

Local setup

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 check runs lint, type checking, unit tests, Worker binding type synchronization checks, and pre-deploy bundle validation all together.

pnpm check
pnpm wrangler dev --local

Cloudflare Access Managed OAuth setup

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

pnpm run 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 the users or ID groups allowed to use the target Cosense project.

3. Copy the Application Audience (AUD) Tag and set it to 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 in the MCP client.

Authorization Code Flow, PKCE, login, refresh tokens, OAuth discovery, and Access Policy are all handled by Cloudflare Access. The Worker itself does not implement an OAuth server.

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

When Managed OAuth is used, the 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

• COSENSE_SID is treated as a Secret binding and is not included in JSON responses or logs.

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

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

• The Origin of /mcp is fully open. Priority is given to compatibility with Remote MCP clients; access control is performed by Cloudflare Access OAuth tokens and JWT verification inside the Worker.

• The MCP tool schemas reject undefined inputs, so callers cannot override the project or credentials.

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

• Tool output is capped at 100,000 characters to avoid unintentionally returning extremely large responses.

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

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