Zuvo Docs

Guide

Model Context Protocol (MCP) Authentication

Integrate Zuvo Auth with MCP servers to authenticate AI agents using your existing user base

The Model Context Protocol (MCP) is an open standard for connecting AI agents and LLM tools to data sources and services. While Zuvo doesn't provide MCP server functionality, you can build your own MCP servers that connect to your Zuvo project and leverage Zuvo Auth's OAuth 2.1 capabilities to authenticate AI agents using your existing user base.

Why use Zuvo Auth for MCP?

When building MCP servers that connect to your Zuvo project, you can leverage your existing Zuvo Auth infrastructure to authenticate AI agents:

  • Use your existing user base - No need to create separate authentication systems; AI agents authenticate as your existing users
  • Standards-compliant OAuth 2.1 - Full implementation with PKCE that MCP clients expect
  • Automatic discovery - MCP clients auto-configure using Zuvo's discovery endpoints
  • Dynamic client registration - MCP clients can register themselves automatically with your project
  • Row Level Security - Your existing RLS policies automatically apply to MCP clients
  • User authorization - Users explicitly approve AI agent access through your authorization flow
  • Token management - Automatic refresh token rotation and expiration handled by Zuvo

How MCP authentication works

When you build an MCP server that connects to your Zuvo project, authentication flows through Zuvo Auth:

  1. Discovery: The MCP client fetches your OAuth configuration from Zuvo's discovery endpoint
  2. Registration (optional): The client registers itself as an OAuth client in your Zuvo project
  3. Authorization: User is redirected to your authorization endpoint to approve the AI tool's access
  4. Token exchange: Zuvo issues access and refresh tokens for the authenticated user
  5. Authenticated access: The MCP server can now make requests to your Zuvo APIs on behalf of the user

By leveraging Zuvo Auth, your MCP server can authenticate AI agents using your existing user accounts without building a separate authentication system.

Prerequisites

Before setting up MCP authentication:

Setting up your MCP server

Configure your MCP server to use your Zuvo Auth server:

https://<project-ref>.supabase.co/auth/v1

Replace <project-ref> with your project reference ID from the Zuvo dashboard.

MCP clients will automatically discover your OAuth configuration from:

https://<project-ref>.supabase.co/.well-known/oauth-authorization-server/auth/v1

OAuth client setup

Depending on your MCP server implementation, you have two options:

  • Pre-register an OAuth client - Manually register your client by following the Register an OAuth client guide and use the client credentials in your MCP server
  • Dynamic client registration - Enable this in Authentication > OAuth Server in your Zuvo dashboard to allow MCP clients to register themselves automatically without manual intervention

Building an MCP server with Zuvo Auth

When building your own MCP server, integrate with Zuvo Auth to authenticate AI agents as your existing users and leverage your RLS policies.

Handling MCP tokens in your application

When your MCP server makes requests to your Zuvo APIs on behalf of authenticated users, it will send access tokens issued by Zuvo Auth, like any other OAuth client.

Validating MCP tokens

Use the same token validation as other OAuth clients.

See Token Security & RLS for more examples.

Security considerations

User approval

Always require explicit user approval for MCP clients:

  • Show clear information about what the AI agent can access
  • Display the client name and description
  • List the scopes being requested
  • Provide an option to deny access
  • Allow users to revoke access later

Troubleshooting

MCP client can't discover OAuth configuration

Problem: Client shows "OAuth discovery failed" or similar error.

Solutions:

  • Verify OAuth 2.1 is enabled in your project
  • Check that /.well-known/oauth-authorization-server returns valid JSON
  • Ensure your project URL is accessible

Dynamic registration fails

Problem: Client receives 403 or 404 on registration endpoint.

Solutions:

  • Enable dynamic client registration in project settings
  • Verify redirect URIs are valid, complete URLs (protocol, domain, path, and port)
  • Check for rate limiting on registration endpoint

Token exchange fails

Problem: Client receives "invalid_grant" error.

Solutions:

  • Verify authorization code hasn't expired (10 minutes)
  • Ensure code verifier matches code challenge
  • Check that redirect URI exactly matches registration
  • Confirm client_id is correct

RLS policies block MCP access

Problem: MCP client can't access data despite valid token.

Solutions:

  • Check RLS policies include the MCP client's client_id
  • Verify user has necessary permissions
  • Test with secret key to isolate RLS issues
  • Review Token Security guide

Next steps