Identity Admin MCP Server

# Identity Admin MCP Server

Cloudflare Worker MCP server that exposes a focused Identity-Service admin toolset.

Endpoints

• GET /healthz is public and returns service health.

• /mcp is the MCP Streamable HTTP endpoint and requires Authorization: Bearer <MCP_CLIENT_TOKEN>.

Related MCP server: Remote MCP Server on Cloudflare

Configuration

Secrets must be configured outside source control:

pnpm install
pnpm exec wrangler secret put MCP_CLIENT_TOKEN
pnpm exec wrangler secret put IDENTITY_ADMIN_TOKEN

Non-secret variables:

• IDENTITY_BASE_URL: Identity-Service base URL.

• MCP_DEFAULT_CHANNEL: default mutation channel when a tool call omits channel (mcp by default).

For local development, use an uncommitted .dev.vars file.

Tools

Admin operation mutation tools require an explicit idempotencyKey, generate a per-call correlationId, default channel from MCP_DEFAULT_CHANNEL, and call Identity-Service only through @cesco_valle/identity-auth-sdk/admin. auth.decideApproval decides an already-anchored approval using the Identity contract.

• auth.createUser

• auth.assignProjectRole

• auth.revokeProjectAccess

• auth.revokeSession

• auth.banUser

• auth.unbanUser

• auth.readmitProjectMembership

• auth.decideApproval

• auth.listProjectUsers

• auth.getUserAccessStatus

• auth.listPendingApprovals

Conversational clients

Tool calls return both redacted JSON text content and matching structuredContent so Claude, Codex, Telegram gateways, and other conversational clients can show readable summaries while using structured data for UI state. List-style Identity responses keep the raw redacted result intact and may add structuredContent.client.list with defensive metadata such as itemCount, detected item key, pagination fields, and action hints.

The server also exposes guidance resources/prompts for safe admin workflow, pagination, Telegram gateway responsibilities, and the no-direct-DB Identity boundary when supported by the installed MCP TypeScript SDK.

Telegram gateway contract

A Telegram gateway should authenticate to /mcp with Authorization: Bearer <MCP_CLIENT_TOKEN>, keep /healthz as a public health check, render concise text content to operators, and use structuredContent for buttons, pagination state, approval summaries, and safe follow-up actions. It must not forward secrets to chat clients.

Architecture decisions

• ADR-0001: runtime and deployment model.

• ADR-0002: discrete auth.* tool boundary.

• ADR-0003: local agent instructions and ADR skill lock.

Commands

pnpm typecheck
pnpm test
pnpm build
pnpm dev

Security notes

• No OAuth v1.

• No direct database access.

• Tool responses include JSON text content and matching structuredContent, with common secret fields redacted in both.