Notes MCP Server with Auth0 & Express
A Model Context Protocol (MCP) server built with Express.js and Passport.js that authenticates users via Auth0 and provides tools to interact with a Notes API.
Features
- ✅ whoami: Get current user's Auth0 profile and claims
- ✅ list-notes: Fetch notes from Notes API using authenticated user's token
- ✅ Auth0 OAuth 2.0 authentication flow
- ✅ Session-based authentication with Passport.js
- ✅ SSE transport for MCP protocol
- ✅ Platform agnostic (runs anywhere Node.js works)
Architecture```
MCP Client → Express Server → Auth0 → Notes API
↓
Passport.js
↓
Session Storage
## Prerequisites
- Node.js 18+ and npm
- Auth0 account with application configured
- Notes API running (default: http://localhost:3000)
## Quick Setup
### 1. Install Dependencies```bash
npm install
2. Configure Auth0
- Create Auth0 Application (Regular Web Application)
-
Configure Application Settings:
- Allowed Callback URLs:http://localhost:3001/callback
- Allowed Logout URLs:http://localhost:3001
- Allowed Web Origins:http://localhost:3001 -
Create Auth0 API for your Notes API:
- Identifier:https://notes-api(or your custom identifier)
- Signing Algorithm: RS256
- Permissions: Addread:notesscope
3. Configure Environment
Copy .dev.vars.example to .env:```bash
cp .dev.vars.example .env
Edit `.env` with your Auth0 credentials:```env
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your_client_id_here
AUTH0_CLIENT_SECRET=your_client_secret_here
AUTH0_CALLBACK_URL=http://localhost:3001/callback
AUTH0_AUDIENCE=https://notes-api
SESSION_SECRET=generate-a-strong-random-secret
API_BASE_URL=http://localhost:3000
PORT=3001
NODE_ENV=development
Generate SESSION_SECRET:```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
### 4. Start the Server
**Development** (with auto-reload):```bash
npm run dev
Production:```bash
npm run build
npm start
Server will start at: `http://localhost:3001`
## Usage
### 1. Authentication Flow
1. Visit `http://localhost:3001`
2. Click "Login" to authenticate with Auth0
3. After successful login, you'll be redirected back
### 2. MCP Client Connection
Configure your MCP client to connect to:```
http://localhost:3001/mcp/sse
The server will ensure authentication before allowing MCP connections.
3. Available Tools
whoami
Returns current user's profile and Auth0 claims:```json
{
"profile": {
"id": "auth0|...",
"displayName": "John Doe",
"emails": [{"value": "john@example.com"}]
},
"claims": {
"sub": "auth0|...",
"email": "john@example.com",
"aud": "...",
"iat": 1234567890
}
}
#### `list-notes`
Fetches notes from the Notes API using the user's access token:```json
[
{
"id": 1,
"title": "My Note",
"content": "Note content",
"userId": "auth0|..."
}
]
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Home page (shows login status) |
/login |
GET | Initiates Auth0 login |
/callback |
GET | Auth0 callback URL |
/logout |
GET | Logs out user and redirects to Auth0 logout |
/mcp/sse |
GET | MCP SSE transport (requires authentication) |
/health |
GET | Health check endpoint |
Notes API Requirements
Your Notes API must:
1. Accept JWT tokens from Auth0 in Authorization: Bearer header
2. Validate tokens against your Auth0 tenant
3. Have an endpoint at /api/notes that returns user-specific notes
Example NestJS Auth Middleware```typescript
@Injectable()
export class Auth0JwtMiddleware implements NestMiddleware {
async use(req: Request, res: Response, next: NextFunction) {
const token = req.headers.authorization?.replace('Bearer ', '');
// Validate token with Auth0
const jwks = jose.createRemoteJWKSet(
new URL(`https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`)
);
const { payload } = await jose.jwtVerify(token, jwks, {
audience: process.env.AUTH0_AUDIENCE,
issuer: `https://${process.env.AUTH0_DOMAIN}/`,
});
req.user = payload;
next();
}
}
## Deployment
### Local Development```bash
npm run dev
Production Deployment
Option 1: Node.js Server (Railway, Heroku, AWS, etc.)```bash
npm run build
npm start
**Option 2: Docker**```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
CMD ["node", "dist/index.js"]
Option 3: PM2```bash
npm install -g pm2
npm run build
pm2 start dist/index.js --name mcp-notes
## Troubleshooting
### "Missing required environment variables"
- Ensure all variables in `.env` are set
- Check that `.env` file exists in project root
### "Invalid Compact JWS" from Notes API
- Verify `AUTH0_AUDIENCE` matches your Auth0 API identifier
- Ensure Notes API is validating tokens correctly
- Check that access token is being sent in Authorization header
### MCP Connection Fails
- Ensure you're authenticated (visit `/login` first)
- Check that MCP client URL is `http://localhost:3001/mcp/sse`
- Verify server is running and accessible
### Session Issues
- Generate a strong `SESSION_SECRET`
- In production, set `NODE_ENV=production` for secure cookies
- Use Redis or database for session storage in production (currently in-memory)
## Project Structure```
notes-mcp/
├── src/
│ ├── index.ts # Express app and MCP server setup
│ ├── auth.ts # Passport Auth0 configuration
│ └── types.ts # TypeScript type definitions
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env # Environment variables (create from .dev.vars.example)
└── README.md # This file
Comparison with Cloudflare Version
| Feature | Cloudflare Workers | Express.js |
|---|---|---|
| Deployment | Cloudflare only | Any platform |
| Dependencies | Cloudflare-specific | Standard Node.js |
| Session Storage | Durable Objects + KV | In-memory or Redis |
| Setup Complexity | High | Medium |
| Cost | Cloudflare pricing | Server hosting |
License
MIT
