MCP Server

Node.js + Express MCP server for ChatGPT with:

• OAuth 2.0 Authorization Code Flow + PKCE S256
• refresh token rotation
• Supabase Postgres persistence
• MCP Streamable HTTP endpoint at /mcp
• sample tools: calculator, get_weather, search_web
• cleanup job for expired OAuth records

Structure

mcp-server/
|-- .env.example
|-- IMPLEMENTATION_REPORT.md
|-- package.json
|-- README.md
|-- supabase/
|   `-- schema.sql
`-- src/
    |-- app.js
    |-- server.js
    |-- config/
    |-- mcp/
    |-- middleware/
    |-- routes/
    |-- scripts/
    |-- services/
    |-- tools/
    `-- utils/

1. Supabase setup

1. Create a Supabase project.
2. Open the SQL editor.
3. Run supabase/schema.sql.
4. Copy the Postgres connection string into .env as DATABASE_URL.

For IPv4-only networks, use the Supabase Session Pooler URI instead of the direct IPv6 connection string.

Seed an OAuth client

You need at least one record in oauth_clients.

For local development the server can seed one automatically from env:

• AUTO_SEED_CLIENT_ID
• AUTO_SEED_CLIENT_NAME
• AUTO_SEED_CLIENT_SECRET
• AUTO_SEED_REDIRECT_URIS

If AUTO_SEED_CLIENT_SECRET is empty, the client is treated as public and may use none auth at the token endpoint. If it is set, the client supports both client_secret_basic and client_secret_post.

2. Local setup

cd mcp-server
npm install
copy .env.example .env

Edit .env:

• BASE_URL
• DATABASE_URL
• CORS_ORIGINS
• MCP_ALLOWED_ORIGINS
• MCP_ALLOWED_HOSTS
• ENABLE_CLEANUP_JOB
• CLEANUP_INTERVAL_MINUTES
• AUTO_SEED_*

Check database connectivity:

npm run db:check
npm run db:init

Run locally:

npm run dev

Health check:

GET http://localhost:3000/healthz

Run cleanup manually:

npm run cleanup:run

3. Expose with ngrok

ngrok http 3000

Take the HTTPS URL from ngrok and set it as:

• BASE_URL
• add the ngrok origin to MCP_ALLOWED_ORIGINS
• add the ngrok host to MCP_ALLOWED_HOSTS
• one of the registered redirect URIs in oauth_clients

Restart the server after updating .env.

4. OAuth endpoints

Authorization endpoint

• GET /authorize
• POST /authorize/decision
• demo consent screen with optional auto-approve mode
• validates:
  • client_id
  • redirect_uri
  • response_type=code
  • code_challenge
  • code_challenge_method=S256
  • scopes

Token endpoint

• POST /token
• supports:
  • grant_type=authorization_code
  • grant_type=refresh_token

Client authentication:

• none
• client_secret_basic
• client_secret_post

Discovery

• GET /.well-known/oauth-authorization-server
• GET /.well-known/openid-configuration

Revoke

• POST /revoke

5. Refresh token rotation

This server rotates refresh tokens on every refresh request:

1. the current refresh token row is locked
2. the old refresh token is revoked
3. a new access token is issued
4. a new refresh token is issued
5. rotation lineage is stored in Postgres

If a revoked or replaced refresh token is reused:

• the backing mcp_session is marked compromised
• session tokens are revoked
• the request fails with invalid_grant

6. MCP endpoint

Main MCP endpoint:

• POST /mcp

Behavior:

• uses MCP Streamable HTTP transport
• path is /mcp
• bearer access token is required
• host and origin allowlists are enforced
• the implementation is stateless on the transport layer
• each HTTP request creates a fresh MCP server and transport instance
• no in-memory MCP transport session map is retained across requests or restarts

Compatibility note:

• GET /mcp and DELETE /mcp currently return 405
• this server is using the stateless streamable HTTP pattern, not SSE session transport

7. Sample tools

• calculator
• get_weather
• search_web

These are in src/tools/ and registered via src/mcp/tool-registry.js.

8. Cleanup job

The server starts a background cleanup job on boot when ENABLE_CLEANUP_JOB=true.

It removes:

• expired or stale authorization codes
• expired or revoked access tokens older than 1 day
• expired or revoked refresh tokens older than 7 days

Interval is controlled by CLEANUP_INTERVAL_MINUTES.

9. Register in ChatGPT

Use your deployed server values:

• Authorization URL: https://your-domain/authorize
• Token URL: https://your-domain/token
• Revoke URL: https://your-domain/revoke
• MCP URL: https://your-domain/mcp

Recommended scopes:

• mcp.tools.call
• offline_access

PKCE:

• required
• method: S256

If ChatGPT or your connector uses a confidential client:

• create the client in oauth_clients
• store the secret hash
• allow client_secret_basic and/or client_secret_post

10. Security notes

• token values are stored hashed in Postgres
• client secrets are stored hashed
• rate limiting is applied to /authorize, /token, /revoke
• OAuth errors use standard fields:
  • error
  • error_description
• raw secrets and tokens are not logged
• refresh token reuse triggers session compromise handling

11. Current status

Verified against real Supabase:

• npm run db:check
• npm run db:init
• npm run cleanup:run

What is still intentionally basic:

1. the consent page is a demo flow, not a real user login system
2. access tokens are opaque and require a DB lookup
3. there is no automated test suite yet
4. rate limits and allowlists should be tightened before production