---

name: mcp-bridge description: > Use the MCP Code Execution Bridge for context-efficient access to Supabase and shadcn tools. Provides API-based database operations (query, insert, update, delete) that work without Docker/MCP servers. Use when you need database access or component management without loading all tool definitions into context. allowed-tools: Bash, Read, Write, Edit, Glob, Grep

MCP Code Execution Bridge

Use scripts/mcp/ for context-efficient MCP tool access. This follows the "Code Execution with MCP" pattern - instead of loading all MCP tool definitions into context, you discover and execute tools through CLI/API wrappers.

When to Use This Skill

Use the MCP Bridge when:

1. Database Operations - Query, insert, update, delete data via REST API
2. MCP Servers Disabled - API tools work without MCP servers enabled
3. No Docker Available - API tools don't require local Supabase
4. Reducing Context Overhead - Avoid loading all MCP definitions upfront
5. Component Management - Search and install shadcn components

MCP Unified Server (Recommended)

For best performance, use the unified HTTP server instead of CLI:

Start the server:

Copynpm run mcp:server

Access the WebUI:

Copyhttp://localhost:3456/ui

Features:

• 🚀 ~50ms per call (vs ~800ms CLI)
• 🔄 Hot reload when tools are added
• 🖥️ WebUI for browsing and executing tools
• 📊 Execution history tracking
• 🔒 Single-instance protection

API Endpoints:

Copy# Discovery
curl http://localhost:3456/mcp/servers
curl http://localhost:3456/mcp/stats
curl "http://localhost:3456/mcp/tools/search?q=database"

# Execute tools
curl -X POST http://localhost:3456/mcp/servers/supabase/tools/list-users/run \
  -H "Content-Type: application/json" -d '{}'

# View history
curl http://localhost:3456/mcp/history

Quick Start - Database Queries

Query a table:

Copynpm run mcp -- run supabase query-table '{"table":"profiles","limit":5}'

Query with filters:

Copynpm run mcp -- run supabase query-table '{"table":"transactions","select":"id,status,property_address","filter":"status=eq.active","limit":10}'

Insert a row:

Copynpm run mcp -- run supabase insert-row '{"table":"contacts","data":{"name":"John","email":"john@example.com"}}'

Update rows:

Copynpm run mcp -- run supabase update-rows '{"table":"profiles","filter":"id=eq.abc-123","data":{"name":"Updated"}}'

Delete rows:

Copynpm run mcp -- run supabase delete-rows '{"table":"contacts","filter":"id=eq.abc-123"}'

Quick Start - SQL Queries (Most Powerful)

Execute any SQL:

Copynpm run mcp -- run supabase run-sql '{"query":"SELECT * FROM profiles LIMIT 5"}'

List all tables:

Copynpm run mcp -- run supabase run-sql '{"query":"SELECT tablename FROM pg_tables WHERE schemaname = '\''public'\'' ORDER BY tablename"}'

Create a table:

Copynpm run mcp -- run supabase run-sql '{"query":"CREATE TABLE test (id serial PRIMARY KEY, name text)"}'

Check RLS policies:

Copynpm run mcp -- run supabase run-sql '{"query":"SELECT tablename, policyname FROM pg_policies WHERE schemaname = '\''public'\''"}'

Quick Start - Storage

List buckets:

Copynpm run mcp -- run supabase list-buckets '{}'

List files in bucket:

Copynpm run mcp -- run supabase list-files '{"bucket":"documents","path":""}'

Get public URL:

Copynpm run mcp -- run supabase get-public-url '{"bucket":"images","path":"logo.png"}'

Upload a file from local path (auto-detects content type):

Copynpm run mcp -- run supabase upload-file '{"bucket":"documents","path":"contracts/deal.pdf","filePath":"./local/contract.pdf"}'

Upload a file (base64 encoded):

Copynpm run mcp -- run supabase upload-file '{"bucket":"documents","path":"contracts/deal.pdf","content":"JVBERi0xLjQK...","contentType":"application/pdf"}'

Download a file:

Copynpm run mcp -- run supabase download-file '{"bucket":"documents","path":"contracts/deal.pdf"}'

Quick Start - Auth Admin (User Management)

Create a user:

Copynpm run mcp -- run supabase create-user '{"email":"agent@realty.com","password":"secure123","email_confirm":true}'

List users:

Copynpm run mcp -- run supabase list-users '{"page":1,"per_page":50}'

Get user by ID:

Copynpm run mcp -- run supabase get-user '{"id":"user-uuid-here"}'

Update user:

Copynpm run mcp -- run supabase update-user '{"id":"user-uuid","email":"new@example.com","user_metadata":{"role":"admin"}}'

Ban user for 24 hours:

Copynpm run mcp -- run supabase update-user '{"id":"user-uuid","ban_duration":"24h"}'

Delete user:

Copynpm run mcp -- run supabase delete-user '{"id":"user-uuid"}'

Quick Start - Edge Functions

Invoke an Edge Function:

Copynpm run mcp -- run supabase invoke-function '{"name":"hello-world","payload":{"name":"John"}}'

Invoke with service role key (for admin functions):

Copynpm run mcp -- run supabase invoke-function '{"name":"admin-task","useServiceRole":true,"payload":{"action":"cleanup"}}'

List deployed Edge Functions:

Copynpm run mcp -- run supabase list-functions '{}'

Quick Start - TypeScript Types (via API)

Generate types to console:

Copynpm run mcp -- run supabase generate-types-api '{}'

Generate types to file:

Copynpm run mcp -- run supabase generate-types-api '{"outputPath":"src/types/database.ts"}'

Generate types with multiple schemas:

Copynpm run mcp -- run supabase generate-types-api '{"includedSchemas":["public","auth"]}'

Quick Start - BoldSign E-Signature

List documents with status filter:

Copynpm run mcp -- run boldsign list-documents '{"status":"sent","pageSize":10}'

Get detailed document status:

Copynpm run mcp -- run boldsign get-document-status '{"documentId":"your-document-id"}'

Send reminder to pending signers:

Copynpm run mcp -- run boldsign send-reminder '{"documentId":"your-document-id"}'

Check webhook processing health:

Copynpm run mcp -- run boldsign webhook-health '{"hours":24}'

List recent webhook events:

Copynpm run mcp -- run boldsign list-webhook-events '{"limit":20}'

Get audit trail for compliance:

Copynpm run mcp -- run boldsign get-audit-trail '{"documentId":"your-document-id","format":"json"}'

List available templates:

Copynpm run mcp -- run boldsign list-templates '{"searchTerm":"purchase"}'

Test webhook endpoint:

Copynpm run mcp -- run boldsign test-webhook '{"eventType":"document.completed"}'

Check BoldSign configuration:

Copynpm run mcp -- run boldsign get-config-status '{}'

Quick Start - Stripe Payments

List customers:

Copynpm run mcp -- run stripe list-customers '{"limit":10}'

Search customer by email:

Copynpm run mcp -- run stripe list-customers '{"email":"customer@example.com"}'

Get customer with payment methods:

Copynpm run mcp -- run stripe get-customer '{"customerId":"cus_abc123","includePaymentMethods":true}'

List recent payments:

Copynpm run mcp -- run stripe list-payments '{"limit":10}'

Get payment details (debug failures):

Copynpm run mcp -- run stripe get-payment '{"paymentIntentId":"pi_abc123"}'

List subscriptions by status:

Copynpm run mcp -- run stripe list-subscriptions '{"status":"active","limit":10}'

Get subscription with upcoming invoice:

Copynpm run mcp -- run stripe get-subscription '{"subscriptionId":"sub_abc123","includeUpcomingInvoice":true}'

List invoices for customer:

Copynpm run mcp -- run stripe list-invoices '{"customerId":"cus_abc123","status":"paid"}'

List all products:

Copynpm run mcp -- run stripe list-products '{"active":true}'

List subscription prices:

Copynpm run mcp -- run stripe list-prices '{"type":"recurring","active":true}'

List prices for a product:

Copynpm run mcp -- run stripe list-prices '{"productId":"prod_abc123"}'

Check account balance:

Copynpm run mcp -- run stripe get-balance '{}'

List disputes (chargebacks):

Copynpm run mcp -- run stripe list-disputes '{"limit":10}'

List webhook events:

Copynpm run mcp -- run stripe list-webhook-events '{"type":"payment_intent.succeeded","limit":20}'

Check webhook health:

Copynpm run mcp -- run stripe webhook-health '{"hours":24}'

Create test customer (test mode only):

Copynpm run mcp -- run stripe create-test-customer '{"email":"test@example.com","addTestPaymentMethod":true}'

Check Stripe configuration:

Copynpm run mcp -- run stripe get-config-status '{}'

Available Servers

Supabase (24 API tools + 6 CLI tools)

PostgREST API Tools (CRUD operations):

Management API Tools (SQL execution - MOST POWERFUL):

Storage Bucket Tools:

Storage File Tools:

Auth Admin API Tools (user management):

Edge Function Tools:

Management API Tools (requires access token):

CLI-Based Tools (require local Supabase/Docker):

shadcn (4 tools)

BoldSign (13 tools)

Document Management:

Document Actions:

Template Management:

Webhook & Debugging:

Stripe (15 tools)

Customer Management:

Payment Management:

Subscription Management:

Product & Pricing:

Invoice Management:

Webhook & Debugging:

Financial Tools:

Testing Tools:

PostgREST Filter Syntax

The filter parameter uses PostgREST syntax:

Multiple filters: Use & to combine: status=eq.active&agent_id=eq.abc-123

CLI Commands Reference

Copy# Discovery
npm run mcp:list                     # List servers
npm run mcp -- list-tools supabase   # List tools
npm run mcp -- describe supabase query-table  # Tool details
npm run mcp:search "database"        # Search tools

# Execution
npm run mcp -- run <server> <tool> '<json>'

# Execution Flags
npm run mcp -- run supabase list-users '{}' --quiet  # Data only, no metadata wrapper
npm run mcp -- run supabase run-sql --input-file query.json  # Read JSON from file (Windows-friendly)

# Convenience Shortcuts
npm run mcp:count transactions       # Quick row count for any table
npm run mcp:users                    # List users (formatted)
npm run mcp:users -- --json          # List users (raw JSON)

# Maintenance
npm run mcp:registry                 # Regenerate after adding tools

CLI Flags

Use --quiet for scripting:

Copy# Get just the data, no wrapper
npm run mcp -- run supabase list-users '{}' --quiet

Use --input-file for Windows or complex JSON:

Copy# Create input file
echo '{"query": "SELECT * FROM profiles LIMIT 5"}' > query.json

# Run with file input
npm run mcp -- run supabase run-sql --input-file query.json

Tool Discovery Pattern

Copy# 1. Find relevant tools
npm run mcp:search "query"

# 2. Get tool details and input schema
npm run mcp -- describe supabase query-table

# 3. Execute with JSON input
npm run mcp -- run supabase query-table '{"table":"profiles"}'

Error Handling

All tools return structured results:

Copy{
  "success": true,
  "data": [...],
  "metadata": {
    "tool": "query-table",
    "server": "supabase",
    "executionTimeMs": 150,
    "executionType": "api"
  }
}

Error response:

Copy{
  "success": false,
  "error": {
    "code": "HTTP_400",
    "message": "HTTP 400: Bad Request",
    "details": {
      "hint": "Perhaps you meant to reference the column..."
    }
  }
}

Environment Variables

API tools use credentials from .env:

Copy# PostgREST and Storage API
VITE_SUPABASE_URL=https://xxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJ...
VITE_SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Management API (required for run-sql)
SUPABASE_ACCESS_TOKEN=sbp_xxx...

# Stripe API (required for stripe tools)
STRIPE_SECRET_KEY=sk_test_xxx...  # or sk_live_... for production
STRIPE_WEBHOOK_SECRET=whsec_xxx...

Get Supabase access token from: Supabase Dashboard > Account > Access Tokens Get Stripe keys from: Stripe Dashboard > Developers > API keys

Creating New Tools

See ADDING-TOOLS.md for step-by-step guide.

Quick steps:

1. Add types to scripts/mcp/types/<server>.types.ts
2. Create wrapper at scripts/mcp/servers/<server>/<tool-name>.ts
3. Export from scripts/mcp/servers/<server>/index.ts
4. Run npm run mcp:registry

See Also

• ADDING-TOOLS.md - Creating new tools
• REFERENCE.md - Complete API reference
• scripts/mcp/README.md - Bridge documentation