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:

npm run mcp:server

Access the WebUI:

http://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:

# 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:

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

Query with filters:

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

Insert a row:

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

Update rows:

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

Delete rows:

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

Quick Start - SQL Queries (Most Powerful)

Execute any SQL:

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

List all tables:

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

Create a table:

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

Check RLS policies:

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

Quick Start - Storage

List buckets:

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

List files in bucket:

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

Get public URL:

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

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

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

Upload a file (base64 encoded):

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

Download a file:

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

Quick Start - Auth Admin (User Management)

Create a user:

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

List users:

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

Get user by ID:

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

Update user:

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

Ban user for 24 hours:

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

Delete user:

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

Quick Start - Edge Functions

Invoke an Edge Function:

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

Invoke with service role key (for admin functions):

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

List deployed Edge Functions:

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

Quick Start - TypeScript Types (via API)

Generate types to console:

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

Generate types to file:

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

Generate types with multiple schemas:

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

Quick Start - BoldSign E-Signature

List documents with status filter:

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

Get detailed document status:

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

Send reminder to pending signers:

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

Check webhook processing health:

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

List recent webhook events:

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

Get audit trail for compliance:

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

List available templates:

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

Test webhook endpoint:

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

Check BoldSign configuration:

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

Quick Start - Stripe Payments

List customers:

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

Search customer by email:

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

Get customer with payment methods:

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

List recent payments:

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

Get payment details (debug failures):

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

List subscriptions by status:

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

Get subscription with upcoming invoice:

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

List invoices for customer:

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

List all products:

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

List subscription prices:

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

List prices for a product:

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

Check account balance:

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

List disputes (chargebacks):

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

List webhook events:

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

Check webhook health:

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

Create test customer (test mode only):

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

Check Stripe configuration:

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

Available Servers

Supabase (24 API tools + 6 CLI tools)

PostgREST API Tools (CRUD operations):

Tool	Description	Example
query-table	Query tables via PostgREST	{"table":"profiles","limit":5}
insert-row	Insert a row	{"table":"contacts","data":{...}}
update-rows	Update rows (filter required)	{"table":"profiles","filter":"id=eq.x","data":{...}}
delete-rows	Delete rows (filter required)	{"table":"contacts","filter":"id=eq.x"}

Management API Tools (SQL execution - MOST POWERFUL):

Tool	Description	Example
run-sql	Execute ANY SQL query	{"query":"SELECT * FROM profiles LIMIT 5"}

Storage Bucket Tools:

Tool	Description	Example
list-buckets	List all storage buckets	{}
create-bucket	Create a new bucket	{"name":"images","public":true}
delete-bucket	Delete bucket (must be empty)	{"name":"old-bucket"}
get-bucket	Get bucket details	{"name":"documents"}

Storage File Tools:

Tool	Description	Example
list-files	List files in bucket	{"bucket":"documents","path":""}
delete-file	Delete files	{"bucket":"documents","paths":["old.pdf"]}
move-file	Move/rename file	{"bucket":"docs","fromPath":"a.pdf","toPath":"b.pdf"}
get-public-url	Get public URL (public bucket)	{"bucket":"images","path":"logo.png"}
create-signed-url	Get temporary signed URL	{"bucket":"docs","path":"contract.pdf"}
upload-file	Upload file (from path or base64)	{"bucket":"docs","path":"file.pdf","filePath":"./local.pdf"}
download-file	Download file from bucket	{"bucket":"docs","path":"contract.pdf"}

Auth Admin API Tools (user management):

Tool	Description	Example
create-user	Create a new user	{"email":"user@example.com","password":"secure123"}
list-users	List all users with pagination	{"page":1,"per_page":50}
get-user	Get user by ID	{"id":"user-uuid"}
update-user	Update user properties	{"id":"user-uuid","email":"new@example.com"}
delete-user	Delete a user	{"id":"user-uuid"}

Edge Function Tools:

Tool	Description	Example
invoke-function	Invoke an Edge Function	{"name":"hello","payload":{"key":"value"}}
list-functions	List deployed functions	{}

Management API Tools (requires access token):

Tool	Description	Example
run-sql	Execute ANY SQL query	{"query":"SELECT * FROM profiles LIMIT 5"}
generate-types-api	Generate TypeScript types	{"outputPath":"src/types/database.ts"}

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

Tool	Description
list-tables	List tables with schema info
execute-sql	Execute raw SQL
apply-migration	Apply DDL migrations
get-logs	Get service logs
get-advisors	Security/performance advisors
generate-types	Generate TypeScript types

shadcn (4 tools)

Tool	Description	Example
search-items	Search components	{"registries":["@shadcn"],"query":"button"}
view-items	View component details	{"items":["@shadcn/button"]}
get-examples	Get usage examples	{"registries":["@shadcn"],"query":"button-demo"}
get-add-command	Get install command	{"items":["@shadcn/button","@shadcn/card"]}

BoldSign (13 tools)

Document Management:

Tool	Description	Example
list-documents	List/search documents	{"status":"sent","pageSize":10}
get-document-status	Get detailed status with signers	{"documentId":"abc-123"}
send-reminder	Remind pending signers	{"documentId":"abc-123"}
extend-expiry	Extend document deadline	{"documentId":"abc-123","additionalDays":30}

Document Actions:

Tool	Description	Example
get-audit-trail	Get signing events and timestamps	{"documentId":"abc-123","format":"json"}
revoke-document	Cancel pending document	{"documentId":"abc-123","reason":"Terms changed"}

Template Management:

Tool	Description	Example
list-templates	List available templates	{"searchTerm":"purchase","pageSize":10}
get-template	Get template details	{"templateId":"abc-123"}
send-from-template	Send doc from template	{"templateId":"abc-123","roles":[...]}

Webhook & Debugging:

Tool	Description	Example
list-webhook-events	Query webhook history	{"documentId":"abc-123","limit":10}
webhook-health	Check webhook processing	{"hours":24}
test-webhook	Send test webhook payload	{"eventType":"document.completed"}
get-config-status	Check BoldSign config	{}

Stripe (15 tools)

Customer Management:

Tool	Description	Example
list-customers	List/search customers	{"email":"user@example.com","limit":10}
get-customer	Get customer with payment methods	{"customerId":"cus_abc","includePaymentMethods":true}

Payment Management:

Tool	Description	Example
list-payments	List PaymentIntents	{"customerId":"cus_abc","status":"succeeded"}
get-payment	Get payment with charge details	{"paymentIntentId":"pi_abc"}

Subscription Management:

Tool	Description	Example
list-subscriptions	List subscriptions by status	{"status":"active","limit":10}
get-subscription	Get subscription with billing	{"subscriptionId":"sub_abc","includeUpcomingInvoice":true}

Product & Pricing:

Tool	Description	Example
list-products	List products (plans, one-time)	{"active":true,"limit":10}
list-prices	List prices by product/type	{"type":"recurring","productId":"prod_abc"}

Invoice Management:

Tool	Description	Example
list-invoices	List invoices for customer	{"customerId":"cus_abc","status":"paid"}

Webhook & Debugging:

Tool	Description	Example
list-webhook-events	Query Stripe events	{"type":"payment_intent.succeeded","limit":20}
webhook-health	Check webhook processing	{"hours":24}

Financial Tools:

Tool	Description	Example
get-balance	Get account balance	{}
list-disputes	List chargebacks	{"limit":10}

Testing Tools:

Tool	Description	Example
create-test-customer	Create test customer (test mode)	{"email":"test@example.com","addTestPaymentMethod":true}
get-config-status	Check Stripe config	{}

PostgREST Filter Syntax

The filter parameter uses PostgREST syntax:

Operator	Meaning	Example
eq	Equals	status=eq.active
neq	Not equals	status=neq.cancelled
gt	Greater than	price=gt.100000
gte	Greater than or equal	price=gte.100000
lt	Less than	price=lt.500000
lte	Less than or equal	price=lte.500000
like	Pattern match	name=like.*John*
ilike	Case-insensitive pattern	name=ilike.*john*
in	In list	status=in.(active,pending)
is	Is null/true/false	deleted_at=is.null

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

CLI Commands Reference

# 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

Flag	Description	Example
--quiet, -q	Output data only (no metadata wrapper)	--quiet
--input-file, -f	Read JSON input from file	--input-file input.json

Use --quiet for scripting:

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

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

# 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

# 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:

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

Error response:

{
  "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:

# 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