Skip to main content
Glama
Neon Contacts MCP Server

Neon Contacts MCP Server

neon-mcp-oauth

An MCP server on Neon Functions that uses OAuth 2.1 from Neon Auth's OAuth provider plugin instead of a static bearer token. Each user signs in, approves the client, and the tools read and write only that user's rows in Lakebase Postgres.

Companion repo for the DevOps Daily post OAuth for MCP Servers on Neon. It follows neon-mcp-demo, the static-token version.

npm install
npx neon link --project-id <your project>      # a project in aws-us-east-2, aws-us-east-1, aws-eu-central-1 or aws-ap-southeast-1
npx neon deploy                                 # neon.ts turns on Neon Auth
psql "$DATABASE_URL" -f db/schema.sql
npx neon functions deploy contacts --src functions/contacts
F=$(npx neon functions get contacts | awk '/^URL/ {print $2}' | sed 's:/$::')
npx neon functions deploy contacts --src functions/contacts --env "MCP_RESOURCE=$F/mcp"
npx neon neon-auth domain add "$F"
npx neon neon-auth config oauth-server update --enabled \
  --login-page "$F/auth/sign-in" --consent-page "$F/auth/consent" \
  --mcp-resource "$F/mcp" --mcp-client-id-metadata-documents

DCR is off by default on a newly configured provider, and these commands keep whatever setting the branch has. Check npx neon neon-auth config oauth-server get; to change it, PATCH the OAuth provider API with "mcp": {"resource": "$F/mcp", "dynamic_registration": false}.

Then add $F/mcp to an MCP client, for example claude mcp add --transport http neon-contacts "$F/mcp" or codex mcp add neon-contacts --url "$F/mcp". Create a user first. There is no sign-up page:

curl -X POST "$NEON_AUTH_BASE_URL/sign-up/email" -H "Origin: $F" -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","password":"<a long password>","name":"Alice"}'

db/schema.sql is for a fresh database. To upgrade the July demo's database, add owner_id with a migration and assign the existing rows first.

What is in it

Path

What it does

functions/contacts/index.ts

The function. /mcp with four contact tools, guarded by @neon/oauth (signature, iss, aud), plus the protected resource metadata (RFC 9728). Contact reads, updates and deletes filter on the token's sub; inserts set owner_id from it.

functions/contacts/pages.ts

The login and consent pages Neon Auth redirects to. Plain HTML, CSP with frame-ancestors 'none'. The consent page shows the client name as unverified, how the client was identified, the host that receives the code, a localhost warning, each scope in plain words, and what the token can do in the app.

db/schema.sql

contacts (with owner_id) and oauth_events, which logs page views and MCP calls so the client tests have evidence.

scripts/client.ts

Scripted MCP client on the MCP TypeScript SDK. --mode cimd or --mode dcr. Signs in, calls tools, refreshes.

scripts/browser-user.ts, scripts/lib/user.ts

A headless Chromium "user" for the browser step: sign in, read the consent page, Allow or Deny, capture the redirect. Used for Claude Code, Codex and Inspector too.

scripts/attacks.ts

20 assertions on expected statuses, response values and refresh error codes: missing, garbage and forged tokens, a token for another resource, a token from a child branch, user isolation, refresh rotation and reuse, revocation, DCR off. A section that throws counts as a failure. It also runs a verifier with no issuer check, to show what that check stops.

results/

Everything recorded on 2026-11-18. Codes and states are redacted.

Related MCP server: Demo Database MCP

Results (2026-11-18)

Client

Registration

Result

Claude Code 2.1.327

CIMD (https://claude.ai/oauth/claude-code-client-metadata)

Connected, listed and called tools

Codex CLI 0.167.0

CIMD (https://chatgpt.com/oauth/codex/client.json)

Connected, listed and called tools

MCP Inspector CLI 2.16.0, defaults

DCR

A fresh registration fails while DCR is off ("does not support dynamic client registration"); works with DCR on

MCP Inspector CLI 2.16.0, --client-metadata-url

CIMD (your own hosted document)

Connected, listed tools

Scripted SDK client

CIMD / DCR

Both connected; refresh rotates

Claude.ai custom connector

CIMD (https://claude.ai/oauth/mcp-oauth-client-metadata), callback on claude.ai

Connected, listed tools, created and found a contact (tested by a person in a browser)

ChatGPT (web: Plugins > Add plugin > custom MCP server)

CIMD (https://chatgpt.com/oauth/client.json), callback on chatgpt.com

Connected, listed tools, called search_contacts (tested by a person in a browser)

Claude Code and Codex ran on one machine and the headless browser on another, so their logins used --no-browser and a pasted redirect URL.

results/attacks.json: 20 of 20 checks passed. Three results are worth reading first:

  • A token from a child branch (same signing keys, aud copied from the parent) is refused by @neon/oauth, and accepted by a verifier that checks only the signature and audience, with the same sub as the user on the parent branch.

  • After you revoke a refresh token, the access token still works at /mcp. Neon Auth refuses to revoke JWT access tokens (unsupported_token_type), and they live 1 hour.

  • Turning DCR off does not remove clients registered while it was on (results/metadata/dcr-lookalike-after-dcr-off.txt).

Limits found

  • Scopes are fixed (openid, profile, email, offline_access). There is no contacts:write; tool permissions must live in your own code.

  • A client that sends no scope (Claude Code does not) gets all four on the consent screen.

  • CIMD client_id URLs cannot be on a Neon domain, so you cannot host your own client document on a Neon Function.

  • Self-onboarding (CIMD or DCR) works for the MCP resource only.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to safely query one or more PostgreSQL databases with read-only tools and explicitly approved write operations.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables database querying and modification through an MCP server where each action is gated by human-granted scopes, per-call confirmations for destructive operations, and revocable access.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables secure read-only PostgreSQL access from MCP clients via OAuth 2.1, with JWT validation, role-based and row-level isolation, and an AST-based SQL guard for audited, safe queries.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to securely connect to your data through a remote deployment with OAuth 2.1 and PKCE, configurable sign-in, read/write consent, and audit logging. It exposes public tools without sign-in and authenticated tools that respect each user's permissions while validating arguments and recording every call.
      Apache 2.0