journal-mcp-server

A reference implementation of a remote MCP (Model Context Protocol) server extracted from a personal journaling app. It exposes journal read/write operations as typed tools that any MCP-compatible agent (Claude, GPT, etc.) can call over HTTP.

Built to demonstrate agent tool design, permission scoping, and OAuth 2.0 integration in a real-world single-user scenario.

What this is

The journaling app this was extracted from stores daily entries with a happiness score (1–10). This MCP layer lets an AI assistant — connected via claude.ai or Claude Desktop — read, write, and analyse those entries on behalf of the owner.

The interesting design challenges this solves:

• One owner, one agent. No multi-tenancy required, but the auth model still uses proper OAuth 2.0 so it works with Claude's connector UI without any custom SDK.

• Bearer token pinned to OAuth secret. The issued access_token is the same value as the bearer token the /mcp route checks, so the OAuth consent flow and the API auth layer are a single secret — no separate token store.

• Stateless transport. Each HTTP request creates a fresh MCP session. No WebSocket, no persistent server-side session.

• Storage abstracted behind an interface. The JournalStore interface lets you swap the backing store (in-memory → SQLite → Postgres) without touching the tool definitions.

Related MCP server: ai-journal

Architecture

claude.ai / Claude Desktop
        │
        │  POST /mcp  (Bearer token)
        ▼
┌─────────────────────────────────────────┐
│  Express app                            │
│                                         │
│  mcpAuth middleware                     │  ← validates bearer token,
│      │                                  │    sets req.mcpUserId
│      ▼                                  │
│  handleMcpRequest()                     │  ← creates MCP session per request
│      │                                  │
│      ▼                                  │
│  McpServer (Streamable HTTP transport)  │
│      │                                  │
│      ▼                                  │
│  JournalStore interface                 │  ← swappable backing store
└─────────────────────────────────────────┘

OAuth endpoints (same server):
  GET  /.well-known/oauth-authorization-server  → RFC 8414 metadata
  GET  /oauth/authorize                         → consent page
  POST /oauth/authorize                         → issue auth code
  POST /oauth/token                             → exchange code for token

Tools

All tools are defined with Zod schemas so the MCP SDK generates accurate JSON Schema for the agent's tool-use call.

Auth model

Bearer token (primary)

Every POST /mcp request must include:

Authorization: Bearer <MCP_TOKEN>

On a 401 the server returns a WWW-Authenticate header pointing to the OAuth metadata URL, which allows MCP clients that support dynamic discovery to kick off the OAuth flow automatically.

OAuth 2.0 (for claude.ai connector UI)

Claude's connector UI only accepts OAuth credentials, not raw bearer tokens. This server implements a minimal Authorization Code flow (RFC 6749) with PKCE (RFC 7636) and server metadata (RFC 8414):

1. Claude fetches /.well-known/oauth-authorization-server to discover endpoints.

2. Claude redirects the user to /oauth/authorize — a consent page served by this server.

3. The user clicks Allow. The server issues a one-time auth code (5-minute TTL).

4. Claude exchanges the code at /oauth/token. The server validates PKCE and returns MCP_TOKEN as the access_token.

5. Claude uses the token as a bearer token on all subsequent /mcp calls.

Credentials to enter in Claude's connector UI:

Transport

Streamable HTTP (MCP spec §3.2) — the server creates a fresh StreamableHTTPServerTransport for every request. This is the simplest MCP transport: no WebSocket handshake, no persistent connection, works through any HTTP reverse proxy.

Running locally

# 1. Install dependencies
npm install

# 2. Configure secrets
cp .env.example .env
# Edit .env — set MCP_TOKEN, MCP_USER_EMAIL, OAUTH_CLIENT_ID

# 3. Start the dev server (auto-reloads on file changes)
npm run dev

The server starts on port 3000 by default. Test with:

# Should return 401 with WWW-Authenticate header
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Should return tool list
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your MCP_TOKEN>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# OAuth metadata
curl http://localhost:3000/.well-known/oauth-authorization-server

Swapping the backing store

The JournalStore interface in src/journalStore.ts is the only contract the MCP tools depend on. To use a real database:

1. Implement JournalStore against your ORM or query builder of choice.

2. Pass your implementation to handleMcpRequest(store, req, res) in src/server.ts.

The InMemoryJournalStore included here is suitable for local development and testing — data is lost on server restart.

Environment variables

Related projects

• Riley-Claude-Skills — Riley's versioned Claude Skills portfolio: reusable instruction sets for PM workflows, personal finance, and more.

License

MIT