What Supabase MCP server does
Supabase MCP server gives MCP-compatible AI assistants access to Supabase projects. Through its tools, an assistant can work with database tables, query project data, retrieve configuration details, and perform other operations exposed by Supabase's configured feature groups.
The hosted endpoint is intended for connecting tools such as Cursor, Claude, Windsurf, and other MCP clients. Access is project-aware: the client can authenticate to Supabase and select the organization containing the target project. A generated connection URL from the Supabase dashboard can also identify project-specific settings.
Use this server when an AI workflow needs to inspect or modify Supabase resources through natural-language tool calls. Apply read-only and project-scoped settings when the assistant should have narrower access.
How it works
The standard connection uses the streamable HTTP endpoint at https://mcp.supabase.com/mcp. MCP clients send tool requests to that endpoint after the user signs in to Supabase. Configuration can be supplied as URL parameters, including a project reference, read-only mode, and selected feature groups.
Supabase CLI installations expose a local endpoint at http://localhost:54321/mcp. Self-hosted Supabase deployments can enable their own MCP endpoint. Both local and self-hosted modes provide a smaller set of tools and do not include OAuth 2.1.
Applications using the Vercel AI SDK can import createToolSchemas() from @supabase/mcp-server-supabase. The schemas let MCP tools be used as static AI SDK tools with client-side validation and inferred TypeScript input and output types. The package also provides createSupabaseMcpHandler() for serving the tools from an application-owned HTTP endpoint.
Setup and configuration
Configure an MCP client with the hosted URL in the format it expects. A typical configuration is:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}
During setup, the client prompts for Supabase login. Select the organization that owns the project to be used. The Supabase dashboard includes an MCP connection tab and a URL builder for generating project-specific connection settings.
Useful URL options include:
project_ref: restricts the connection to one project.read_only=true: removes mutating tools.features: selects feature groups such as database and docs.
Review Supabase's MCP security guidance before granting an AI assistant access to a project. For a custom HTTP deployment, provide a platform adapter to createSupabaseMcpHandler() and manage handler lifetime around each request when credentials vary per request. A shared handler can be retained for a shared service credential.
Tools and capabilities
Available capabilities include:
- Managing Supabase database tables.
- Querying Supabase data.
- Fetching project configuration.
- Restricting tools to selected feature groups.
- Excluding account-level tools for project-scoped connections.
- Excluding mutating operations with read-only mode.
- Generating typed tool schemas for the Vercel AI SDK.
- Hosting the MCP interface from a custom HTTP endpoint.
- Collecting request lifecycle results and Supabase-provided facts through an observer.
The complete tool set depends on the selected configuration and deployment mode. The observer receives lifecycle information and bounded built-in facts; it does not automatically receive request or response payloads.
Limitations and notes
Local CLI and self-hosted environments have fewer tools than the hosted service and do not provide OAuth 2.1. MCP tool results do not include structuredContent; integrations using the AI SDK must rely on JSON contained in the text content fallback.
Custom observers can add facts without automatic privacy validation. Observer, classifier, and sink failures do not alter request behavior, although synchronous observer or classifier work can block requests. The custom handler supports the current protocol revision and rejects clients that only speak the 2025-era protocol.
The package is licensed under Apache 2.0.