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.

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

Runnable Convex example

Compare your setup with a working mcp-use Convex server.

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

Configure Convex

Set environment variables

Configure the MCP server

Use Convex identity in tools

Verify the setup

Next steps

Runnable Convex example

Convex OAuth Provider component

User Context

​Configure Convex

​Set environment variables

​Configure the MCP server

​Use Convex identity in tools

​Verify the setup

​Next steps

Runnable Convex example

Convex OAuth Provider component

User Context

Configure Convex

Set environment variables

Configure the MCP server

Use Convex identity in tools

Verify the setup

Next steps