MCP OAuth — Convex

An mcp-use MCP server template that verifies access tokens from your Convex OAuth Provider deployment. Includes a whoami tool that returns the authenticated user's identity and scopes.

Deploy to Manufact

Prerequisites

• Node.js 22.22.2 or newer and npm.

• A Convex project with the Convex OAuth Provider component configured, including working login and consent screens. Convex Auth alone is not an OAuth authorization server.

This template runs the MCP resource server. Your Convex deployment owns user accounts, login, consent, client registration, and token issuance.

Related MCP server: mcp-gateway

Configure Convex

1. Follow the OAuth Provider component setup in your Convex project.

2. Enable Dynamic Client Registration so MCP clients can register automatically; it is disabled by default in the component.

3. Allow the openid profile email scopes.

4. Note the complete OAuth issuer URL, including the mounted path, for example https://your-deployment-name.convex.site/oauth.

Run locally

Create a repository from this template or clone it:

git clone https://github.com/manufacts/mcp-oauth-convex-template.git
cd mcp-oauth-convex-template
npm ci
cp .env.example .env

Edit .env to point at your Convex OAuth Provider:

MCP_USE_OAUTH_CONVEX_AUTH_URL=https://your-deployment-name.convex.site/oauth

Start the development server:

npm run dev

Connect an OAuth-capable MCP client to http://localhost:3000/mcp. You can also use the Inspector link printed by the CLI. Set the Inspector Scope to openid profile email if your client does not send scopes by default, complete login and consent through Convex, then call whoami.

Available tool

whoami returns the verified subject ID, OAuth client ID (when present), scopes, permissions, token expiry, and MCP resource URL. Add your own tools in src/index.ts and use ctx.auth for the authenticated identity.

Deploy

Use the deploy link above, or run:

npx mcp-use deploy

Set MCP_USE_OAUTH_CONVEX_AUTH_URL in the deployment's environment before starting the server. For public or tunnel deployments, set MCP_URL to the public server origin, such as https://mcp.example.com, without /mcp.

To build and run yourself:

npm run typecheck
npm run build
npm start

Verify authentication

• A request without a bearer token must be rejected.

• MCP resource metadata must point at your Convex OAuth issuer.

• An OAuth-capable client must register, complete login and consent, and successfully call whoami with a valid token.

• Invalid or expired tokens must be rejected.

Troubleshooting

• Missing environment variable: copy .env.example to .env and set the issuer URL, or configure it in your hosting environment.

• Registration fails: enable Dynamic Client Registration on the Convex OAuth Provider component.

• Login or consent fails: check the login and consent routes in your Convex application; these are hosted separately from this MCP server.

• Token rejected: check that the issuer matches your Convex OAuth endpoint and that the token was issued for this MCP resource. For remote deployments, verify MCP_URL matches the public origin.

Learn more

• mcp-use Convex authentication documentation

• Convex OAuth Provider component

License

MIT