This server enables developers to manage and interact with self-hosted Supabase instances through the Model Context Protocol (MCP), providing comprehensive database management tools:
Database Operations: List tables and extensions, execute SQL queries, generate TypeScript types, and access database statistics
Migration Management: List and apply SQL migration scripts
Configuration Access: Retrieve project URL, anonymous key, service role key, and verify JWT secret
User Authentication: List, retrieve, create, update, and delete auth users (note: some operations require direct DB access)
Storage Management: List storage buckets and objects within buckets
Monitoring Tools: View active connections, database stats, and Realtime publications
Development Utilities: Restart the pg_net worker
Provides tools for direct PostgreSQL database operations, including executing SQL queries, viewing database connections and statistics, listing extensions, and querying system catalogs.
Enables interaction with self-hosted Supabase instances, providing tools for database introspection, SQL query execution, schema management, migrations, auth user management, storage bucket operations, and TypeScript type generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Self-Hosted Supabase MCP Server show me the list of tables in the database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project provides a Model Context Protocol (MCP) server designed specifically for interacting with self-hosted Supabase instances. It bridges the gap between MCP clients (like IDE extensions) and your local or privately hosted Supabase projects, enabling database introspection, management, and interaction directly from your development environment.
This server was built from scratch, drawing lessons from adapting the official Supabase cloud MCP server, to provide a minimal, focused implementation tailored for the self-hosted use case.
Related MCP server: Self-Hosted Supabase MCP Server
The primary goal of this server is to enable developers using self-hosted Supabase installations to leverage MCP-based tools for tasks such as:
Querying database schemas and data.
Managing database migrations.
Inspecting database statistics and connections.
Managing authentication users.
Interacting with Supabase Storage.
Generating type definitions.
It avoids the complexities of the official cloud server related to multi-project management and cloud-specific APIs, offering a streamlined experience for single-project, self-hosted environments.
Tools are categorized by privilege level:
Regular tools are accessible by any authenticated Supabase JWT (authenticated or service_role role).
Privileged tools require a service_role JWT (HTTP mode) or direct database/service-key access (stdio mode).
Tool | Description | Privilege |
| Lists tables in the database schemas | Regular |
| Lists installed PostgreSQL extensions | Regular |
| Lists all available (installable) extensions | Regular |
| Lists applied migrations from | Regular |
| Applies a SQL migration and records it in | Privileged |
| Lists columns for a specific table | Regular |
| Lists indexes for a specific table | Regular |
| Lists constraints for a specific table | Regular |
| Lists foreign keys for a specific table | Regular |
| Lists triggers for a specific table | Regular |
| Lists user-defined database functions | Regular |
| Gets the source definition of a function | Regular |
| Gets the source definition of a trigger | Regular |
Tool | Description | Privilege |
| Executes an arbitrary SQL query | Privileged |
| Runs | Privileged |
| Shows active connections ( | Regular |
| Retrieves database statistics ( | Regular |
| Shows index usage statistics | Regular |
| Shows pgvector index statistics | Regular |
Tool | Description | Privilege |
| Lists Row-Level Security policies for a table | Regular |
| Shows RLS enabled/disabled status for tables | Regular |
| Retrieves security and performance advisory notices | Regular |
Tool | Description | Privilege |
| Returns the configured Supabase URL | Regular |
| Checks if the JWT secret is configured | Regular |
Tool | Description | Privilege |
| Generates TypeScript types from the database schema | Regular |
| Restarts the | Privileged |
| Retrieves recent log entries (analytics stack or CSV fallback) | Regular |
Tool | Description | Privilege |
| Lists users from | Regular |
| Retrieves details for a specific user | Regular |
| Creates a new user in | Privileged |
| Updates user details (password bcrypt-hashed if changed) | Privileged |
| Deletes a user from | Privileged |
Tool | Description | Privilege |
| Lists all storage buckets | Regular |
| Lists objects within a specific bucket | Regular |
| Retrieves storage bucket configuration | Regular |
| Updates storage bucket settings | Privileged |
Tool | Description | Privilege |
| Lists PostgreSQL publications (e.g. | Regular |
Tool | Description | Privilege |
| Lists scheduled jobs (requires | Regular |
| Shows recent execution history for a cron job | Regular |
| Lists pgvector indexes (requires | Regular |
Tool | Description | Privilege |
| Lists deployed Edge Functions | Regular |
| Gets details and metadata for an Edge Function | Regular |
| Retrieves recent logs for an Edge Function | Regular |
supabase_migrations.schema_migrationsThe list_migrations and apply_migration tools rely on the supabase_migrations.schema_migrations table. This table is created and managed by the Supabase CLI — it is not part of the MCP server itself.
How the table is created:
The table is automatically created when you initialise or run migrations using the Supabase CLI:
supabase db push # pushes local migrations to a remote database
supabase migration up # applies pending local migration filesIf you have never run the Supabase CLI against your database, the table will not exist and list_migrations will return an error. You can create it manually with:
CREATE SCHEMA IF NOT EXISTS supabase_migrations;
CREATE TABLE IF NOT EXISTS supabase_migrations.schema_migrations (
version text NOT NULL PRIMARY KEY,
name text NOT NULL DEFAULT '',
inserted_at timestamptz NOT NULL DEFAULT now()
);Schema difference vs. official Supabase:
The Supabase cloud platform tracks additional columns (e.g. statements, dirty). This MCP server uses the minimal schema (version + name + inserted_at) that is compatible with the Supabase CLI's local-development workflow. If your existing table has extra columns they are simply ignored.
To install Self-Hosted Supabase MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claudeBun v1.1 or later (replaces Node.js/npm — used for runtime and builds)
Access to your self-hosted Supabase instance (URL, keys, and optionally a direct PostgreSQL connection string).
Clone the repository:
git clone <repository-url>
cd selfhosted-supabase-mcpInstall dependencies:
bun installBuild the project:
bun run buildThis compiles the TypeScript source to JavaScript in the dist directory.
The server requires configuration details for your Supabase instance. These can be provided via command-line arguments or environment variables. CLI arguments take precedence.
Required:
--url <url> or SUPABASE_URL=<url>: The main HTTP URL of your Supabase project (e.g., http://localhost:8000).
--anon-key <key> or SUPABASE_ANON_KEY=<key>: Your Supabase project's anonymous key.
Optional (but Recommended/Required for certain tools):
--service-key <key> or SUPABASE_SERVICE_ROLE_KEY=<key>: Your Supabase project's service role key. Required for privileged tools and for auto-creating the execute_sql helper function on startup.
--db-url <url> or DATABASE_URL=<url>: The direct PostgreSQL connection string for your Supabase database (e.g., postgresql://postgres:password@localhost:5432/postgres). Required for tools needing direct database access (apply_migration, Auth tools, Storage tools, pg_catalog queries).
--jwt-secret <secret> or SUPABASE_AUTH_JWT_SECRET=<secret>: Your Supabase project's JWT secret. Required when using --transport http and needed by the verify_jwt_secret tool.
--tools-config <path>: Path to a JSON file specifying which tools to enable (whitelist). If omitted, all tools are enabled. Format: {"enabledTools": ["tool_name_1", "tool_name_2"]}.
HTTP transport options (when using --transport http):
--port <number>: HTTP server port (default: 3000).
--host <string>: HTTP server host (default: 127.0.0.1).
--cors-origins <origins>: Comma-separated list of allowed CORS origins. Defaults to localhost only.
--rate-limit-window <ms>: Rate limit window in milliseconds (default: 60000).
--rate-limit-max <count>: Max requests per rate limit window (default: 100).
--request-timeout <ms>: Request timeout in milliseconds (default: 30000).
execute_sql Helper Function: Many tools rely on a public.execute_sql function within your Supabase database for SQL execution via RPC. The server attempts to check for this function on startup. If it's missing and a service-key and db-url are provided, it will attempt to create the function automatically. If creation fails or keys aren't provided, tools relying solely on RPC may fail.
Direct Database Access: Tools interacting directly with privileged schemas (auth, storage) or system catalogs (pg_catalog) generally require DATABASE_URL to be configured.
Coolify / reverse-proxy deployments:
The DATABASE_URL must use the internal hostname reachable from wherever the MCP server process runs, not the public-facing domain.
An ECONNRESET error during startup means the DATABASE_URL cannot be reached from the server's network context.
The server will still start successfully and all tools that don't require a direct DB connection will continue to work normally.
When running with --transport http, the server enforces:
JWT authentication on all /mcp endpoints using your SUPABASE_AUTH_JWT_SECRET.
Privilege-based access control (RBAC) — the role claim in the JWT determines which tools are accessible:
service_role: Full access (all tools including privileged ones).
authenticated: Regular tools only.
anon: No tool access.
Rate limiting — configurable request rate limit per IP address.
CORS — configurable allow-list of origins (defaults to localhost only).
Security headers — X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, etc.
Request timeouts — configurable timeout to prevent resource exhaustion.
Stdio mode has no authentication — all tools (including privileged ones) are accessible. It is intended for trusted local clients only (e.g., an IDE extension running on your local machine). A warning is printed on startup when this mode is used.
create_auth_user and update_auth_user accept a plain-text password from the MCP client, then immediately hash it with bcrypt (via PostgreSQL's pgcrypto extension: crypt($password, gen_salt('bf'))) before storing it in auth.users. The plain-text password is never stored. Passwords are passed as query parameters (not string-interpolated into SQL), preventing SQL injection.
Note: The password travels over the MCP transport in plain text between the MCP client and server. This is inherent to the MCP protocol interface and unavoidable at this layer. Use the HTTP transport with TLS termination (e.g., behind Kong/nginx) for network protection.
All database operations in the MCP server use parameterized queries ($1, $2, ...) to prevent SQL injection. The execute_sql tool is an intentional exception — it executes arbitrary SQL by design (it is the tool's purpose). This tool is restricted to service_role privilege level to limit exposure.
Run the server using Bun, providing the necessary configuration:
# Using CLI arguments (stdio mode — default)
bun run dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> \
--db-url postgresql://postgres:password@localhost:5432/postgres \
--service-key <your-service-key>
# Example with tool whitelisting via config file
bun run dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> \
--tools-config ./mcp-tools.json
# Or configure using environment variables and run:
# export SUPABASE_URL=http://localhost:8000
# export SUPABASE_ANON_KEY=<your-anon-key>
# export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
# export SUPABASE_SERVICE_ROLE_KEY=<your-service-key>
bun run dist/index.jsbun run dist/index.js \
--transport http \
--port 3100 \
--host 0.0.0.0 \
--url http://kong:8000 \
--anon-key <your-anon-key> \
--service-key <your-service-key> \
--jwt-secret <your-jwt-secret> \
--db-url postgresql://postgres:password@db:5432/postgresHTTP mode requires --jwt-secret. All /mcp requests must include a valid Supabase JWT in the Authorization: Bearer <token> header.
The server communicates via stdio (default) or HTTP (Streamable HTTP Transport) and is designed to be invoked by an MCP client application (e.g., an IDE extension like Cursor). The client will connect to the server's stdio stream or HTTP endpoint to list and call the available tools.
Below are examples of how to configure popular MCP clients to use this self-hosted server.
Important:
Replace placeholders like <your-supabase-url>, <your-anon-key>, <your-db-url>, <path-to-dist/index.js> etc., with your actual values.
Ensure the path to the compiled server file (dist/index.js) is correct for your system.
Be cautious about storing sensitive keys directly in configuration files, especially if committed to version control. Consider using environment variables or more secure methods where supported by the client.
Create or open the file .cursor/mcp.json in your project root.
Add the following configuration:
{
"mcpServers": {
"selfhosted-supabase": {
"command": "bun",
"args": [
"run",
"<path-to-dist/index.js>", // e.g., "/home/user/selfhosted-supabase-mcp/dist/index.js"
"--url",
"<your-supabase-url>", // e.g., "http://localhost:8000"
"--anon-key",
"<your-anon-key>",
// Optional - Add these if needed by the tools you use
"--service-key",
"<your-service-key>",
"--db-url",
"<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres"
"--jwt-secret",
"<your-jwt-secret>",
// Optional - Whitelist specific tools
"--tools-config",
"<path-to-your-mcp-tools.json>" // e.g., "./mcp-tools.json"
]
}
}
}VS Code Copilot allows using environment variables populated via prompted inputs, which is more secure for keys.
Create or open the file .vscode/mcp.json in your project root.
Add the following configuration:
{
"inputs": [
{ "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" },
{ "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true },
{ "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false },
{ "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" },
{ "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false }
],
"servers": {
"selfhosted-supabase": {
"command": "bun",
"args": [
"run",
"${input:sh-supabase-server-path}",
"--tools-config", "${input:sh-supabase-tools-config}"
],
"env": {
"SUPABASE_URL": "${input:sh-supabase-url}",
"SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}",
"SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}",
"DATABASE_URL": "${input:sh-supabase-db-url}",
"SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}"
}
}
}
}When you use Copilot Chat in Agent mode (@workspace), it should detect the server. You will be prompted to enter the details (URL, keys, path) when the server is first invoked.
Adapt the configuration structure shown for Cursor or the official Supabase documentation, replacing the command and args with the bun run command and the arguments for this server, similar to the Cursor example:
{
"mcpServers": {
"selfhosted-supabase": {
"command": "bun",
"args": [
"run",
"<path-to-dist/index.js>",
"--url", "<your-supabase-url>",
"--anon-key", "<your-anon-key>",
"--service-key", "<your-service-key>",
"--db-url", "<your-db-url>",
"--jwt-secret", "<your-jwt-secret>",
"--tools-config", "<path-to-your-mcp-tools.json>"
]
}
}
}Consult the specific documentation for each client on where to place the mcp.json or equivalent configuration file.
This MCP server can be integrated directly into a self-hosted Supabase Docker Compose stack, making it available alongside other Supabase services via the Kong API gateway.
When integrated with Docker:
The MCP server runs in HTTP transport mode (not stdio)
It's exposed through Kong at /mcp/v1/*
JWT authentication is handled by the MCP server itself
The server has direct access to the database and all Supabase keys
From your Supabase Docker directory:
git submodule add https://github.com/HenkDz/selfhosted-supabase-mcp.git selfhosted-supabase-mcpCreate volumes/mcp/Dockerfile:
# Dockerfile for selfhosted-supabase-mcp HTTP mode
# Multi-stage build using Bun runtime for self-hosted Supabase
FROM oven/bun:1.1-alpine AS builder
WORKDIR /app
# Copy package files from submodule
COPY selfhosted-supabase-mcp/package.json selfhosted-supabase-mcp/bun.lock* ./
# Install dependencies
RUN bun install --frozen-lockfile || bun install
# Copy source code
COPY selfhosted-supabase-mcp/src ./src
COPY selfhosted-supabase-mcp/tsconfig.json ./
# Build the application
RUN bun build src/index.ts --outdir dist --target bun
# Production stage
FROM oven/bun:1.1-alpine AS runner
WORKDIR /app
# Create non-root user for security
RUN addgroup --system --gid 1001 mcp && \
adduser --system --uid 1001 --ingroup mcp mcp
# Copy built application from builder
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
# Set ownership
RUN chown -R mcp:mcp /app
USER mcp
# Default environment variables
ENV NODE_ENV=production
# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3100/health || exit 1
# Expose HTTP port
EXPOSE 3100
# Start the MCP server in HTTP mode
CMD ["bun", "run", "dist/index.js"]Add this service definition to your docker-compose.yml:
## MCP Server - Model Context Protocol for AI integrations
## DISABLED BY DEFAULT - Add 'mcp' to COMPOSE_PROFILES to enable
mcp:
container_name: ${COMPOSE_PROJECT_NAME:-supabase}-mcp
profiles:
- mcp
build:
context: .
dockerfile: ./volumes/mcp/Dockerfile
restart: unless-stopped
healthcheck:
test:
[
"CMD",
"wget",
"--no-verbose",
"--tries=1",
"--spider",
"http://localhost:3100/health"
]
timeout: 5s
interval: 10s
retries: 3
depends_on:
db:
condition: service_healthy
rest:
condition: service_started
environment:
SUPABASE_URL: http://kong:8000
SUPABASE_ANON_KEY: ${ANON_KEY}
SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
SUPABASE_AUTH_JWT_SECRET: ${JWT_SECRET}
DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
command:
[
"bun",
"run",
"dist/index.js",
"--transport", "http",
"--port", "3100",
"--host", "0.0.0.0",
"--url", "http://kong:8000",
"--anon-key", "${ANON_KEY}",
"--service-key", "${SERVICE_ROLE_KEY}",
"--jwt-secret", "${JWT_SECRET}",
"--db-url", "postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}"
]Add the MCP routes to volumes/api/kong.yml in the services section:
## MCP Server routes - Model Context Protocol for AI integrations
## Authentication is handled by the MCP server itself (JWT validation)
- name: mcp-v1
_comment: 'MCP Server: /mcp/v1/* -> http://mcp:3100/*'
url: http://mcp:3100/
routes:
- name: mcp-v1-all
strip_path: true
paths:
- /mcp/v1/
plugins:
- name: cors
config:
origins:
- "$SITE_URL_PATTERN"
- "http://localhost:3000"
- "http://127.0.0.1:3000"
methods:
- GET
- POST
- DELETE
- OPTIONS
headers:
- Accept
- Authorization
- Content-Type
- X-Client-Info
- apikey
- Mcp-Session-Id
exposed_headers:
- Mcp-Session-Id
credentials: true
max_age: 3600The MCP service uses Docker Compose profiles, so it's disabled by default. To enable it:
Option A: Set in .env file:
COMPOSE_PROFILES=mcpOption B: Enable at runtime:
docker compose --profile mcp up -dOnce running, the MCP server is available at:
Internal (from other containers): http://mcp:3100
External (via Kong): http://localhost:8000/mcp/v1/
When running in HTTP mode, the MCP server validates JWTs using the configured JWT_SECRET. Clients must include a valid Supabase JWT in the Authorization header:
Authorization: Bearer <supabase-jwt>The JWT's role claim determines access:
service_role: Full access to all tools (regular + privileged)
authenticated: Access to regular tools only
anon: No tool access
The MCP server exposes a health endpoint:
curl http://localhost:8000/mcp/v1/healthWhen deploying via Docker:
The MCP server runs as a non-root user (mcp:mcp)
JWT authentication is enforced for all tool calls
Privileged tools (like execute_sql) require service_role JWT
CORS is configured via Kong - adjust origins for your deployment
Language: TypeScript
Build: bun build (via bun run build)
Runtime: Bun v1.1+
Test runner: bun test
Dependencies: Managed via bun (bun.lock)
Core Libraries: @supabase/supabase-js, pg (node-postgres), zod (validation), commander (CLI args), @modelcontextprotocol/sdk (MCP server framework), express, jsonwebtoken.
This project is licensed under the MIT License. See the LICENSE file for details.
Applies a SQL migration script and records it in the supabase_migrations.schema_migrations table within a transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | The migration version string (e.g., '20240101120000'). | |
| name | No | An optional descriptive name for the migration. | |
| sql | Yes | The SQL DDL content of the migration. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool applies SQL within a transaction and records the migration, indicating it's a write operation with atomicity. However, it lacks details on permissions, error handling, or side effects beyond the transaction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and includes essential details (transactional recording). Every word contributes value with zero waste, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (applies SQL migrations with versioning) and lack of annotations or output schema, the description is adequate but incomplete. It covers the purpose and transactional behavior but omits details on return values, error cases, or integration with sibling tools like list_migrations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the parameters (name, sql, version). The description adds no additional meaning beyond what the schema provides, such as explaining parameter interactions or constraints, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Applies a SQL migration script') and the resource ('records it in the supabase_migrations.schema_migrations table'), distinguishing it from sibling tools like execute_sql or list_migrations by specifying the transactional recording aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for applying SQL migrations with versioning, but does not explicitly state when to use this tool versus alternatives like execute_sql (for general SQL) or list_migrations (for viewing). It provides context but lacks explicit guidance on exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new user directly in auth.users. WARNING: Requires plain password, insecure. Use with extreme caution.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The email address for the new user. | ||
| password | Yes | Plain text password (min 6 chars). WARNING: Insecure. | |
| role | No | User role. | authenticated |
| user_metadata | No | Optional user metadata. | |
| app_metadata | No | Optional app metadata. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates critical behavioral traits: this is a write operation (implied by 'Creates'), it requires a plain password (security risk), and it operates directly on auth.users. The warning about insecurity and extreme caution adds valuable context beyond basic functionality, though it could mention permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with only two sentences that each earn their place: the first states the purpose, and the second provides critical warnings. It's front-loaded with the core functionality and wastes no words, making it highly efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a write operation with security implications), no annotations, and no output schema, the description does well by covering the purpose and major risks. However, it lacks details on what the tool returns (e.g., user ID or confirmation) and doesn't mention prerequisites like admin permissions, leaving some gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain the semantics of 'app_metadata' vs 'user_metadata'). This meets the baseline of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Creates a new user') and target resource ('directly in auth.users'), distinguishing it from sibling tools like 'update_auth_user' or 'delete_auth_user' which modify or remove users rather than create them. It uses precise language that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Creates a new user') and includes a strong warning about security risks ('WARNING: Requires plain password, insecure. Use with extreme caution.'), which implicitly suggests caution and potential alternatives. However, it doesn't explicitly name alternative methods or specify when not to use it beyond the security warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a user from auth.users by their ID. Requires service_role key and direct DB connection.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The UUID of the user to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a destructive operation ('Deletes'), specifies authentication requirements ('Requires service_role key'), and mentions infrastructure dependencies ('direct DB connection'). It doesn't cover rate limits, error conditions, or what happens to associated data, but provides solid foundational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place: the first states the core functionality, the second specifies critical requirements. There's no wasted language or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description does well by specifying the action, target, identifier, and critical requirements. It could be more complete by mentioning what 'deletes' entails (permanent removal vs soft delete) or what happens to user data, but it provides sufficient context for safe invocation given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'user_id' already well-documented in the schema as 'The UUID of the user to delete.' The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Deletes'), target resource ('a user from auth.users'), and identifier mechanism ('by their ID'). It distinguishes from siblings like 'create_auth_user' and 'update_auth_user' by specifying deletion rather than creation or modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('Deletes a user from auth.users by their ID') and mentions prerequisites ('Requires service_role key and direct DB connection'). However, it doesn't explicitly state when NOT to use it or name alternative tools for related operations like 'get_auth_user' or 'list_auth_users'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Executes an arbitrary SQL query against the database, using direct database connection when available or RPC function as fallback.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SQL query to execute. | |
| read_only | No | Hint for the RPC function whether the query is read-only (best effort). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the execution method (direct connection or RPC fallback) but lacks critical details such as whether this tool can perform destructive operations, what permissions are required, how results are returned, or any rate limits. For a tool that executes arbitrary SQL with no safety annotations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the core purpose and implementation details without unnecessary words. It's front-loaded with the main action and avoids redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of executing arbitrary SQL (which can include reads, writes, or schema changes), the lack of annotations, and no output schema, the description is insufficient. It doesn't address safety, permissions, result formats, or error handling, leaving critical gaps for an AI agent to use this tool effectively in varied contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (sql and read_only) with clear descriptions. The description doesn't add any meaningful semantic information beyond what's in the schema, such as SQL dialect specifics or read_only implications. Baseline 3 is appropriate when the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Executes an arbitrary SQL query') and the target resource ('against the database'), with additional implementation details about connection methods. It distinguishes itself from sibling tools like list_tables or get_database_stats by focusing on direct SQL execution rather than predefined operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'direct database connection when available or RPC function as fallback,' suggesting this is a general-purpose SQL execution tool. However, it doesn't explicitly state when to use this versus alternatives like apply_migration for schema changes or list_tables for metadata queries, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates TypeScript types from the database schema using the Supabase CLI (supabase gen types) and downloads the file to the specified absolute path. The tool returns the current platform (win32, darwin, linux) to help with path formatting. Requires DATABASE_URL configuration and Supabase CLI installed.
| Name | Required | Description | Default |
|---|---|---|---|
| included_schemas | No | Database schemas to include in type generation. | |
| output_filename | No | Filename to save the generated types to in the workspace root. | database.types.ts |
| output_path | Yes | Absolute path where to download the generated TypeScript file. Examples: Windows: "C:\\path\\to\\project\\database.types.ts", macOS/Linux: "/path/to/project/database.types.ts". This parameter is required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it downloads a file to a specified path, returns platform information for path formatting, and has prerequisites (DATABASE_URL, Supabase CLI). It does not mention error handling, performance, or rate limits, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first, followed by key behaviors and prerequisites. Every sentence adds necessary information without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involving file generation and external CLI usage), no annotations, and no output schema, the description is reasonably complete. It covers purpose, behavior, and prerequisites, but could benefit from details on error cases or output format beyond platform info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning the use of 'supabase gen types' and platform-specific path examples, but does not provide additional semantic context for parameters like included_schemas or output_filename.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Generates TypeScript types from the database schema') and resource ('using the Supabase CLI'), distinguishing it from sibling tools like list_tables or execute_sql. It precisely defines what the tool does without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (for generating TypeScript types from a Supabase database schema) and mentions prerequisites (DATABASE_URL configuration, Supabase CLI installed). However, it does not explicitly state when not to use it or name specific alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the configured Supabase anon key for this server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavior. It only says 'Returns', implying a read-only operation, but lacks details on potential side effects, authentication requirements, or error conditions. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and front-loaded with the action and result. No wasted words, effectively communicates the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters and no output schema, the description is largely sufficient. However, it could mention the key's typical use (e.g., for public client access) or the need for a connected instance to fully cover the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline for zero-parameter tools is 4; the description adds no parameter-specific meaning but does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns the configured Supabase anon key. The verb 'Returns' and resource 'Supabase anon key' are specific and unambiguous, distinguishing it from sibling tools like get_service_key through the explicit mention of 'anon key'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_service_key for service role key). The description does not specify context or prerequisites, such as needing a connected Supabase instance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves details for a specific user from auth.users by their ID.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The UUID of the user to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'retrieves', which is a read operation, but does not disclose potential side effects, error cases, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool without output schema, the description is minimally adequate. It could benefit from mentioning what 'details' are returned or handling of non-existent users.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds little beyond 'by their ID'. The parameter is already fully described in the schema. No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieves', the resource 'details for a specific user', and the method 'by their ID'. It distinctly separates from siblings like list_auth_users or create_auth_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_auth_users or other user-related tools. The description does not mention context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves information about active database connections from pg_stat_activity.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly implies a read-only operation ('retrieves'), but does not specify what fields are returned, any authentication requirements, or potential impacts. The description is adequate but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It front-loads the verb and resource, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description provides sufficient context for a simple read tool. However, it could mention the typical fields returned (e.g., user, host, state) to improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0 params, 100% schema coverage). The description does not need to explain parameters, and the baseline for 0 params is 4. It adds no parameter info because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieves' and the resource 'information about active database connections from pg_stat_activity'. It distinguishes from sibling tools like get_database_stats and list_tables by specifying the exact system view used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_database_stats or execute_sql. The description lacks any context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves statistics about database activity and the background writer from pg_stat_database and pg_stat_bgwriter.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the source system views but does not disclose potential performance impact, staleness of data, or any prerequisites. Since no annotations are provided, the description carries full responsibility for behavioral disclosure, which it fails to satisfy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's purpose without any extra words. It is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and simple functionality, the description is minimally adequate. However, it could mention typical use cases or what the output contains (e.g., statistical counters) to be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema already covers 100% of the interface. The description does not need to add parameter semantics, and it correctly omits any. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving statistics about database activity and the background writer, naming the specific source views (pg_stat_database and pg_stat_bgwriter). This is distinct from sibling tools like get_database_connections which focus on connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any conditions or typical use cases. The description lacks contextual cues for an agent to decide if this is the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the configured Supabase project URL for this server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose any behavioral traits beyond the obvious read operation. No mention of auth requirements or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal description; lacks specification of the return format (e.g., string, URL format). For a simple tool, it is adequate but leaves room for ambiguity about what 'configured' implies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is trivially 100%. Description adds context about the return value beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns the configured Supabase project URL for the server. Verb 'Returns' and resource are specific, distinguishing it from siblings like get_anon_key or get_service_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, such as when a project URL is needed vs other configuration retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the configured Supabase service role key for this server, if available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It mentions 'if available' but does not address security concerns, permissions required, or implications of retrieving a sensitive key. For a credential-returning tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core function without wasted words. It is appropriately front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sensitivity of returning a service role key, the description lacks warnings about key handling, availability conditions, or output format. With no output schema or annotations, the description should provide more context to ensure safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the input schema is empty (100% coverage). The description adds no parameter details but still clarifies the tool's purpose, which is appropriate given no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the Supabase service role key, which is distinct from sibling tools like get_anon_key and get_project_url. The verb 'Returns' combined with the specific resource 'Supabase service role key' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., get_anon_key). While the context of sibling tools implies differentiation, the description itself lacks 'when to use' or 'when not to use' instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists users from the auth.users table.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of users to return | |
| offset | No | Number of users to skip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states a read operation ('Lists users'), but omits details like pagination behavior, authentication requirements, or side effects. The minimal description does not compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. While it is extremely brief, it is still efficient; however, it could be more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks completeness for a listing tool with no output schema. It does not explain the return format (e.g., array of user objects) or mention pagination behavior beyond parameter defaults. Given the tool's relative simplicity and the 100% schema coverage, more contextual details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (limit, offset). The tool description adds no additional meaning beyond what the schema already provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Lists' and the resource 'users from the auth.users table', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like get_auth_user (single user) and create_auth_user (creation), but does not explicitly highlight this distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_auth_user or search-like tools. The description lacks context for selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all installed PostgreSQL extensions in the database.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits such as permissions needed or whether it is read-only. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Clearly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters, the description is sufficient. However, it could mention the return format (e.g., extension names only) since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, baseline of 4. Description adds no extra meaning beyond schema (empty), but that is acceptable given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Lists' and specific resource 'all installed PostgreSQL extensions in the database,' distinguishing it from sibling tools like list_tables or list_migrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance. Usage is implied but could benefit from mentioning that it is a safe read operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists applied database migrations recorded in supabase_migrations.schema_migrations table.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the purpose but does not disclose read-only nature, authentication requirements, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no extraneous information. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is adequate. It could mention that it's a read-only operation or the format of results, but overall it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is 100%. The description adds no parameter details, but per guidelines, baseline is 4 for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lists') and the specific resource ('applied database migrations') and the source table, making it distinct from sibling tools like apply_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as apply_migration. The description does not provide context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists PostgreSQL publications, often used by Supabase Realtime.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only says 'lists' without disclosing read-only nature, authentication needs, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 10 words, no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters or output schema, the description provides the essential purpose and context. Missing return format is acceptable given no schema burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline is 4. The description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists PostgreSQL publications and hints at the Supabase Realtime context, making it distinct from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives, but the purpose is self-evident given no other sibling tool lists publications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all storage buckets in the project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or response format. Only states the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence that is front-loaded and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter list operation, the description is complete enough. However, it lacks details about the return format or any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% (vacuously). The description adds no additional parameter meaning beyond the schema, aligning with the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all storage buckets in the project, using a specific verb and resource. It distinguishes from siblings like list_storage_objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_storage_objects). The description only states the functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists objects within a specific storage bucket, optionally filtering by prefix.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket_id | Yes | The ID of the bucket to list objects from. | |
| limit | No | Max number of objects to return | |
| offset | No | Number of objects to skip | |
| prefix | No | Filter objects by a path prefix (e.g., 'public/') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions listing and optional prefix filtering but does not disclose pagination behavior (despite limit/offset in schema), auth requirements, or potential side effects. Adequate but has gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 11 words, front-loading the core functionality. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description is minimal. It does not describe the return format (e.g., list of object names, metadata) or any other behavioral details, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what is in the schema; it simply reiterates the prefix filter without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'lists', the resource 'objects within a specific storage bucket', and the optional 'prefix' filter, which distinguishes it from sibling tools like list_storage_buckets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing objects in a bucket but does not provide explicit guidance on when to use versus alternatives like list_storage_buckets, nor any when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all accessible tables in the connected database, grouped by schema.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It only states the action, but omits important traits like whether it is read-only, requires authentication, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates the core action and grouping. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is adequate but lacks details about the return format or structure of the grouped output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. With zero params, the baseline is 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('lists'), the resource ('tables'), and the grouping ('grouped by schema'). It distinguishes from siblings like list_extensions or list_migrations by specifying tables, but does not explicitly say when to use it over others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, nor any prerequisites or exclusions. The agent receives no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attempts to restart the pg_net worker. Requires the pg_net extension to be installed and available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only discloses one behavioral trait (requires extension) but omits side effects, success/failure behavior, or what 'attempts' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words, front-loading the action immediately. It is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description covers the core purpose and a prerequisite. However, it lacks details on return value, error conditions, or what exactly 'restart' entails, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description adds context about extension requirements beyond the empty schema, meeting the baseline expectation for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool attempts to restart the pg_net worker using a specific verb and resource. It distinguishes itself from sibling tools which are unrelated operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (pg_net extension installed) but lacks explicit guidance on when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates fields for a user in auth.users. WARNING: Password handling is insecure. Requires service_role key and direct DB connection.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The UUID of the user to update. | |
| No | New email address. | ||
| password | No | New plain text password (min 6 chars). WARNING: Insecure. | |
| role | No | New role. | |
| user_metadata | No | New user metadata (will overwrite existing). | |
| app_metadata | No | New app metadata (will overwrite existing). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds context beyond the input schema by warning about 'Password handling is insecure' and specifying requirements like 'Requires service_role key and direct DB connection', which are crucial for safe and correct usage. However, it doesn't detail potential side effects or response behavior, preventing a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose and critical warnings in just two sentences. Every sentence earns its place by conveying essential information without waste, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a user update tool with 6 parameters, no annotations, and no output schema, the description is moderately complete. It covers key behavioral aspects like security warnings and prerequisites, but lacks details on return values, error handling, or full mutation implications, which would be beneficial for comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as explaining interactions between fields or usage nuances. This meets the baseline of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Updates' and resource 'fields for a user in auth.users', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'create_auth_user' or 'delete_auth_user' beyond the update action, which keeps it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context with 'Requires service_role key and direct DB connection', implying prerequisites for usage. However, it lacks explicit guidance on when to use this tool versus alternatives like 'create_auth_user' or 'delete_auth_user', leaving usage scenarios somewhat implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks if the Supabase JWT secret is configured for this server and returns a preview.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It states the tool 'Checks' and 'returns a preview', implying a read-only operation with no side effects. However, it does not disclose what happens if the JWT secret is missing or what 'preview' entails exactly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying the exact purpose with no filler. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no parameters, no output schema, and low complexity. Description succinctly covers what it does and what it returns, making it complete for an agent to decide and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so schema coverage is 100%. Description adds no parameter-specific info, which is acceptable given there are none. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Checks' and resource 'Supabase JWT secret', clearly stating the tool's action: verification and preview. It distinguishes itself from sibling tools which perform mutations, listings, or connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. While the purpose implies uses before configuring other operations, the description does not explicitly state context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0generate_typescript_types3 fields changedInput schema / properties / output_filenameAdded value: +{
+ "default": "database.types.ts",
+ "description": "Filename to save the generated types to in the workspace root.",
+ "type": "string"
+}Input schema / properties / output_pathAdded value: +{
+ "description": "Absolute path where to download the generated TypeScript file. Examples: Windows: \"C:\\\\path\\\\to\\\\project\\\\database.types.ts\", macOS/Linux: \"/path/to/project/database.types.ts\". This parameter is required.",
+ "type": "string"
+}Input schema / requiredPrevious value: -[]New value: +[
+ "output_path"
+]apply_migrationcreate_auth_userdelete_auth_userexecute_sqlgenerate_typescript_typesget_anon_keyget_auth_userget_database_connectionsget_database_statsget_project_urlget_service_keylist_auth_userslist_extensionslist_migrationslist_realtime_publicationslist_storage_bucketslist_storage_objectslist_tablesrebuild_hooksupdate_auth_userverify_jwt_secretScored across 21 tools
Most tools have distinct purposes targeting specific Supabase domains like auth, database, storage, and migrations. However, some overlap exists between list_tables and list_extensions/list_migrations as they all list database entities, though their descriptions clarify the specific resources. The auth tools (create/update/delete/get/list_auth_user) are clearly differentiated by action.
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. Examples include apply_migration, create_auth_user, execute_sql, list_tables, and update_auth_user. This predictability makes it easy for agents to understand and select tools.
With 21 tools, the count is on the higher side but reasonable for a self-hosted Supabase server covering multiple domains like auth, database, storage, and migrations. It might feel slightly heavy, but each tool appears to serve a specific function without obvious redundancy.
The toolset provides comprehensive coverage for core Supabase operations, including CRUD for auth users, database queries, migrations, storage, and monitoring. Minor gaps exist, such as no direct tools for managing storage objects (only listing) or handling realtime subscriptions beyond listing publications, but agents can work around these using execute_sql or other tools.
MCP server for interacting with the Supabase platform
Butterbase MCP server — manage your backend: schemas, auth, functions, storage, RAG, deploys.
Xata MCP server lets AI agents interact with your Xata projects, and Postgres database branches.
