Convex Provider

Use the Convex provider when you host your own OAuth authorization server using the Convex OAuth Provider component. MCP clients register directly with your Convex deployment through Dynamic Client Registration, and your MCP server verifies Convex-issued tokens.

Start from the template

Use the Convex OAuth template for a standalone MCP server with an authenticated whoami tool.

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

Configure your Convex OAuth Provider as described below, set MCP_USE_OAUTH_CONVEX_AUTH_URL in .env, then run npm run dev. Connect your MCP client to http://localhost:3000/mcp. The template hosts the MCP resource server. Your Convex deployment must provide the OAuth Provider component, login, consent, and token issuance; Convex Auth alone is not sufficient. You can also deploy the template to Manufact. Set the issuer URL in the deployment environment before starting the server. For public or tunnel deployments, set MCP_URL to the public MCP server origin, without /mcp.

Configure Convex

In your Convex deployment, set up the OAuth Provider component:

Install the Convex OAuth Provider component in your Convex project.
Enable Dynamic Client Registration on the OAuth component so MCP clients can register automatically.
Configure the allowed scopes for your deployment. At minimum, include openid profile email.
Deploy your Convex project and note the base URL of your Convex site. It will look like:

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

Set environment variables

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

This must be the base URL of your Convex OAuth Provider endpoint, without a trailing slash.

Configure the MCP server

import { MCPServer } from "mcp-use";
import { oauthConvexProvider } from "mcp-use/oauth/convex";

const server = new MCPServer({
  name: "convex-server",
  version: "1.0.0",
  oauth: oauthConvexProvider({
    authURL: process.env.MCP_USE_OAUTH_CONVEX_AUTH_URL!,
  }),
});

await server.listen(3000);

You can also pass the URL directly instead of reading from an environment variable:

oauth: oauthConvexProvider({
  authURL: "https://your-deployment-name.convex.site/oauth",
});

Use Convex identity in tools

When a request is authenticated, tools receive the verified Convex identity on ctx.auth.

import { error, object } from "mcp-use";

server.tool(
  {
    name: "whoami",
    description: "Return the verified Convex identity for this request.",
  },
  async (_args, ctx) => {
    if (!ctx.auth) {
      return error("Unauthorized");
    }

    return object({
      id: ctx.auth.user.id,
      clientId: ctx.auth.user.clientId,
      scopes: ctx.auth.scopes,
      permissions: ctx.auth.permissions,
      expiresAt: ctx.auth.expiresAt,
    });
  },
);

Use User Context for broader access-control patterns inside tools.

Verify the setup

Run the server and connect with an OAuth-capable MCP client.

npm run dev

Confirm these cases:

The client discovers Convex OAuth metadata from your MCP server.
The client registers with your Convex deployment.
Authenticated tool calls include ctx.auth.user.id.
Tool calls without a valid bearer token are rejected.

When using the Inspector, set the Scope to openid profile email if the client does not send a scope by default.

Next steps

Convex OAuth template

Clone or deploy a standalone MCP server with Convex authentication.

Convex OAuth Provider component

Set up the OAuth Provider component in your Convex deployment.

User Context

Use Convex identity data inside tools.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Convex Provider

Start from the template

Configure Convex

Set environment variables

Configure the MCP server

Use Convex identity in tools

Verify the setup

Next steps

Convex OAuth template

Convex OAuth Provider component

User Context

​Start from the template

​Configure Convex

​Set environment variables

​Configure the MCP server

​Use Convex identity in tools

​Verify the setup

​Next steps

Convex OAuth template

Convex OAuth Provider component

User Context

Start from the template

Configure Convex

Set environment variables

Configure the MCP server

Use Convex identity in tools

Verify the setup

Next steps