journal-mcp-server

A remote MCP server I pulled out of my ReflectAI journaling app. It lets Claude, or any MCP client, read and write journal entries over HTTP, with OAuth 2.0 sign-in so it works in Claude's connector settings.

I built it to work through agent tool design, permission scoping and OAuth end to end.

What this is

ReflectAI 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.

Design choices

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

• Bearer token pinned to the 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 share a single secret and there's no separate token store.

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

• Storage 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.

Each tool also declares all four MCP behaviour hints, so a host can tell reads from writes before calling:

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 start 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, and it 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

Tests

npm test

The tests call each tool through the MCP SDK's in-memory transport, backed by InMemoryJournalStore. No server, port, or secrets are needed.

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

• ReflectAI: the journaling app this server came from. Live at reflectai.net.

• Riley-Claude-Skills: my Claude skills library.

License

MIT