Skip to main content
Glama
Neon Contacts MCP Server

Neon Contacts MCP Server

README.md
# neon-mcp-oauth

An MCP server on [Neon Functions](https://neon.com/docs/compute/functions/overview) that uses OAuth 2.1 from [Neon Auth's OAuth provider plugin](https://neon.com/docs/auth/guides/plugins/oauth-provider) 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](https://devops-daily.com/posts/neon-mcp-server-oauth)**. It follows [neon-mcp-demo](https://github.com/The-DevOps-Daily/neon-mcp-demo), the static-token version.

```bash
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:

```bash
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. |

## 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