N-US-078 MCP OAuth Spike

Throwaway spike to prove Claude can complete OAuth 2.1 + PKCE against a Nutrivita-hosted MCP server and call a trivial ping tool.

Do not merge to dev. This code is intentionally disposable.

What it does

• Serves RFC 9728 protected-resource metadata and RFC 8414 authorization-server metadata.
• Implements a minimal OAuth 2.1 Authorization Server:
  • GET /oauth/authorize — hardcoded login + consent page.
  • POST /oauth/authorize — issues an authorization code (with PKCE binding and iss).
  • POST /oauth/token — exchanges code for a JWT access token whose aud is the canonical MCP URI.
• Implements a stateless MCP Resource Server over Streamable HTTP:
  • POST /mcp — returns 401 with WWW-Authenticate + as_uri when unauthenticated.
  • Authenticated requests list and call a single ping tool.

Run locally

cd scratch/n-us-078-mcp-oauth-spike
cp .env.example .env
# edit .env: set SPIKE_CLIENT_SECRET and JWT_SECRET
npm run dev

Local curl test

# 1. Discover protected resource metadata
curl http://localhost:3000/.well-known/oauth-protected-resource

# 2. Open the consent page in a browser, approve, and copy the `code` from the URL.
#    Or use the authorize URL directly:
open "http://localhost:3000/oauth/authorize?client_id=n-us-078-spike-client-id&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2Fcallback&scope=mcp%3Aping&code_challenge=abc123&code_challenge_method=S256&state=xyz"

# 3. Exchange the code for an access token
curl -X POST http://localhost:3000/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "n-us-078-spike-client-id",
    "client_secret": "n-us-078-spike-client-secret",
    "code": "PASTE_CODE",
    "redirect_uri": "https://localhost/callback",
    "code_verifier": "PASTE_VERIFIER"
  }'

# 4. Call ping via MCP (Accept must include both application/json and text/event-stream)
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer PASTE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ping"}}'

Note: the MCP transport returns a streamable response, so the body is formatted as an SSE event (event: message\ndata: {...}) even for direct HTTP responses.

Deploy for Claude testing

The server must be on a public host with an IPv4 A record and HTTPS (Claude calls from 160.79.104.0/21).

The recommended approach is a separate subdomain on the existing Nutrivita backend VM so the spike doesn't touch the backend Nginx config.

Deploy on Render (quick option)

If you don't want to touch GCP, Render can host the spike directly. The repo includes a render.yaml blueprint that creates a free Web Service with the required env vars.

1. Create a GitHub repo for the spike

Create a new private GitHub repository (e.g. nutrivita-mcp-oauth-spike). Do not include the Nutrivita main repo.

2. Push the spike files

From this directory, push all files except secrets and dependencies:

# Run in a terminal
git init
git checkout -b main
# Add all the files: package.json, *.mjs, Dockerfile, README.md, .env.example,
# .env.production.example, nginx-mcp-spike.conf, deploy.sh, render.yaml
git add package.json config.mjs oauth.mjs server.mjs test-flow.mjs Dockerfile README.md .env.example .env.production.example nginx-mcp-spike.conf deploy.sh render.yaml
git commit -m "N-US-078 MCP OAuth spike"
git remote add origin https://github.com/YOUR_USER/nutrivita-mcp-oauth-spike.git
git push -u origin main

3. Create the Render service

1. In the Render dashboard, click New → Web Service.
2. Connect the nutrivita-mcp-oauth-spike GitHub repository.
3. Render will detect render.yaml and provision the service automatically.
4. Wait for the build to finish. The service URL will be something like https://nutrivita-mcp-spike.onrender.com.

The render.yaml sets:

• SPIKE_CLIENT_ID = n-us-078-spike-client-id
• SPIKE_CLIENT_SECRET, JWT_SECRET, SPIKE_USER_PASSWORD = Render-generated random secrets
• BASE_URL is derived automatically from RENDER_EXTERNAL_URL.

You can override any of these in the Render Dashboard → Environment tab.

4. Verify

curl https://nutrivita-mcp-spike.onrender.com/.well-known/oauth-authorization-server
curl https://nutrivita-mcp-spike.onrender.com/health

5. Connect in Claude

Use the Render URL as the MCP server endpoint:

• MCP server URL: https://nutrivita-mcp-spike.onrender.com/mcp
• Client ID: n-us-078-spike-client-id
• Client Secret: copy from the Render Dashboard (SPIKE_CLIENT_SECRET)
• Consent password: copy from the Render Dashboard (SPIKE_USER_PASSWORD)

Note: Render's free Web Service sleeps after 15 minutes of inactivity. The first request may take 30–60 seconds to wake up. For the OAuth handshake, either ping /health first or upgrade to a paid instance.

GCP deployment (if you prefer the Nutrivita VM)

1. Prepare environment

Create the production env file and fill in real secrets:

cp .env.production.example .env.production
# edit .env.production

2. Add a DNS record

Create an A record for mcp-spike.nutrivita.asia (or your chosen subdomain) pointing to the external IPv4 address of the nutrivita-backend VM.

3. Run the deploy script

Requires: gcloud CLI authenticated, Docker installed, and permission to push to the project's Artifact Registry.

export GCP_PROJECT_ID=your-project-id
export GCP_REPOSITORY_NAME=your-repo-name
export DOMAIN=mcp-spike.nutrivita.asia
export SSL_EMAIL=admin@nutrivita.asia
chmod +x deploy.sh
./deploy.sh

The script will:

1. Build and push the spike Docker image.
2. SSH into the existing VM and run the container on localhost:3002.
3. Install an Nginx site for the subdomain.
4. Obtain a Let's Encrypt certificate.
5. Test the metadata endpoint.

If you prefer, you can run the same steps manually; see deploy.sh for the exact commands.

4. Verify

curl https://mcp-spike.nutrivita.asia/.well-known/oauth-authorization-server
curl https://mcp-spike.nutrivita.asia/health

5. Connect in Claude

1. In Claude, go to Settings → Custom Connectors → Add connector.
2. Enter the MCP server URL: https://mcp-spike.nutrivita.asia/mcp.
3. In Advanced settings, enter the SPIKE_CLIENT_ID and SPIKE_CLIENT_SECRET from .env.production.
4. On the hardcoded login+consent page, enter the SPIKE_USER_PASSWORD and click Approve.
5. Ask Claude "call ping" and confirm it returns pong.

Capture redirect_uris

During discovery, leave ALLOWED_REDIRECT_URIS unset. The spike logs every redirect_uri sent by Claude. Copy the exact observed values and add them to .env before handing off to N-US-079.

Stop the spike

When the spike is done (pass or fail), delete this directory or keep it on a clearly named branch. Do not merge to develop.