> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convex Provider

> Configure Convex OAuth authentication for a TypeScript MCP server.

Use the Convex provider when you host your own OAuth authorization server using the [Convex OAuth Provider component](https://www.convex.dev/components/codefox-inc/oauth-provider). 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](https://github.com/manufacts/mcp-oauth-convex-template) for a standalone MCP server with an authenticated `whoami` tool.

```bash theme={null}
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](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmanufacts%2Fmcp-oauth-convex-template). 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:

1. Install the [Convex OAuth Provider component](https://www.convex.dev/components/codefox-inc/oauth-provider) in your Convex project.
2. Enable **Dynamic Client Registration** on the OAuth component so MCP clients can register automatically.
3. Configure the allowed scopes for your deployment. At minimum, include `openid profile email`.
4. Deploy your Convex project and note the base URL of your Convex site. It will look like:

```text theme={null}
https://your-deployment-name.convex.site/oauth
```

## Set environment variables

```bash theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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`.

```typescript theme={null}
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](/v2/typescript/server/authentication/user-context) for broader access-control patterns inside tools.

## Verify the setup

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Convex OAuth template" icon="github" href="https://github.com/manufacts/mcp-oauth-convex-template">
    Clone or deploy a standalone MCP server with Convex authentication.
  </Card>

  <Card title="Convex OAuth Provider component" icon="book-open" href="https://www.convex.dev/components/codefox-inc/oauth-provider">
    Set up the OAuth Provider component in your Convex deployment.
  </Card>

  <Card title="User Context" icon="user" href="/v2/typescript/server/authentication/user-context">
    Use Convex identity data inside tools.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.