mcp-mochi-remote

Remote MCP server for Mochi flashcards. Deploy to Vercel, connect from Claude.ai web or mobile as a custom connector, then create and manage flashcards, decks and templates from the chat.

Built on the same Mochi tool catalogue as k-and/mcp-mochi (the stdio variant). Both expose the same tool set – the difference is only in transport and deployment.

Features

• 20 Mochi tools covering flashcards, decks, templates and attachments
• decks and templates resources for discovery
• write-flashcard prompt for well-structured card creation
• Single-user OAuth 2.1 flow gated by a consent password you set
• HMAC-signed JWT access tokens (30-day lifetime)
• Dynamic client registration so Claude.ai self-registers without pre-provisioning
• OAuth metadata endpoints per RFC 8414 and RFC 9728
• Automatic retry on Mochi's per-account concurrency limiter (HTTP 429)

Deploy to Vercel

One-Click

Manual

git clone https://github.com/k-and/mcp-mochi-remote.git
cd mcp-mochi-remote
vercel --prod

Environment Variables

Set these in Vercel's project settings (or copy .env.example to .env.local for local dev):

Variable	Required	Purpose
MOCHI_API_KEY	yes	Your Mochi token. Settings > Account > Subscription > API Keys in Mochi.
OAUTH_JWT_SECRET	yes	HMAC secret for signing access tokens. Generate with the command below.
CONSENT_PASSWORD	yes	Password the authorise page asks for. Pick something strong.
PUBLIC_BASE_URL	no	Optional override. If unset, the public URL is derived from the request's x-forwarded-host and x-forwarded-proto headers, which Vercel populates automatically.

Generate an OAUTH_JWT_SECRET:

node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

Connect to Claude.ai

1. Deploy this project and note the public URL (e.g. https://mcp-mochi-remote.vercel.app)
2. In Claude.ai, open Customize > Connectors, click +, then Add custom connector (path for individual plans; may differ on team plans)
3. Set the remote MCP server URL to <your-deployment>/api/mcp
4. Claude.ai will open the authorise page. Enter your CONSENT_PASSWORD and approve
5. The 20 Mochi tools appear in the chat's tool list. Ask Claude to "create a flashcard about X" or "find my cards about Y"

To disconnect and re-authorise, remove and re-add the connector. The access token is valid for 30 days; after expiry, the authorisation flow runs again.

Security Model

This is a single-user service by design. There is one CONSENT_PASSWORD and one MOCHI_API_KEY; anyone who knows the password gets to act as you.

What the OAuth flow protects:

• The MCP endpoint at /api/mcp is gated by a valid JWT access token
• Access tokens expire after 30 days
• Rotating OAUTH_JWT_SECRET instantly invalidates every outstanding token

What it does NOT protect against:

• Brute-force of the consent password
• Someone with your password impersonating you until the token expires or you rotate the secret
• Anything Mochi's own API exposes to a holder of your API key

If you want per-user isolation, multi-tenant auth or audit trails, this is not the right shape.

Local Development

git clone https://github.com/k-and/mcp-mochi-remote.git
cd mcp-mochi-remote
cp .env.example .env.local
# Fill in MOCHI_API_KEY, OAUTH_JWT_SECRET, CONSENT_PASSWORD, PUBLIC_BASE_URL
npm install
npm run dev

Visit http://localhost:3000/api/mcp for the MCP endpoint and http://localhost:3000/.well-known/oauth-authorization-server for the OAuth metadata.

Useful scripts:

Script	What it does
npm run dev	Next.js dev server with hot reload
npm run build	Production build
npm run typecheck	TypeScript check without emit
npm run start	Serve the production build

Architecture

• Next.js App Router on Vercel serverless functions
• mcp-handler wraps tool registrations behind an HTTP MCP transport (both streamable-HTTP and SSE), plus the withMcpAuth bearer-token check
• jose for HMAC signing and verifying JWTs
• lib/mochi/ owns the Mochi API client, request/response schemas and tool registrations
• lib/oauth/ owns JWT issuance/verification and OAuth metadata
• app/oauth/* routes implement the authorise, token and dynamic-registration endpoints
• app/api/[transport]/route.ts exposes the MCP endpoint itself at /api/mcp