# MCP OAuth — Convex

An [mcp-use](https://github.com/mcp-use/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](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmanufacts%2Fmcp-oauth-convex-template)

## Prerequisites

- Node.js 22.22.2 or newer and npm.
- A Convex project with the [Convex OAuth Provider component](https://www.convex.dev/components/codefox-inc/oauth-provider) 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.

## Configure Convex

1. Follow the [OAuth Provider component setup](https://github.com/codefox-inc/convex-oauth-provider) 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:

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

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

Start the development server:

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

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

```bash
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](https://mcp-use.com/docs/v2/typescript/server/authentication/providers/convex)
- [Convex OAuth Provider component](https://www.convex.dev/components/codefox-inc/oauth-provider)

## License

MIT