Database & MCP

دليل خادم Supabase MCP: ربط وكلاء الذكاء الاصطناعي بـ Postgres

2026-09-02·24 دقيقة دقائق قراءة·LLMPodium Team

إجابة سريعة: يقوم خادم Supabase MCP بربط الوكلاء المستقلين (Claude Code وCursor وWindsurf) بقواعد بيانات PostgreSQL بأمان عبر بروتوكول Model Context Protocol المفتوح. ويوفر فحصاً حياً للمخططات وتنفيذاً آمناً لتعليمات SQL وبحثاً دلالياً عبر pgvector. للتشغيل الآمن في بيئات الإنتاج، يجب فرض صلاحيات القراءة فقط (read-only)، وتجميع الاتصالات عبر PgBouncer/Supavisor (المنفذ 6543)، وتحديد مهلة الاستعلامات والتحقق من صحة SQL عبر شجرة الإعراب النحوي (AST).

1. مقدمة: صعود وكلاء الذكاء الاصطناعي المستقلين لإدارة قواعد البيانات

في عام 2026، تطور وكلاء هندسة البرمجيات المستقلون مثل Claude Code (claude mcp) وCursor والوكلاء المتخصصون في إدارة قواعد البيانات (DBA) ليتجاوزوا مجرد إكمال الأكواد إلى إدارة موثوقية المواقع (SRE) وقواعد البيانات بالكامل. وبدلاً من الاعتماد على ملفات DDL الثابتة والترقيات اليدوية، أصبح الوكلاء يفحصون فهارس PostgreSQL ذاتياً، ويشخصون اختناقات الأداء، ويراقبون بيئات الإنتاج في الوقت الفعلي.

ومع ذلك، فإن ربط وكيل ذكاء اصطناعي مباشرة بقاعدة بيانات الإنتاج يفرض مخاطر جسيمة:

هلوسات مدمرة في DDL/DML: تنفيذ غير مقصود لأوامر DROP TABLE أو TRUNCATE أو أوامر UPDATE ... WHERE دون شروط تصفية على ملايين السجلات.
استنزاف مجمع الاتصالات (Connection Exhaustion): تشغيل مئات مسارات الأدوات المتزامنة مما يستنزف حد max_connections في ثوانٍ ويؤدي لتعطل التطبيق.
حقن SQL وتصعيد الصلاحيات: استغلال هجمات حقن الأوامر (Prompt Injection) في مدخلات المستخدمين لدفع الوكيل إلى تنفيذ استعلامات غير مصرح بها أو تسريب بيانات حساسة.
تضخم نافذة السياق: إرسال مخططات قواعد بيانات ضخمة تحتوي على مئات الجداول إلى نافذة السياق، مما يستهلك الرموز ويزيد تكاليف الاستدلال بصورة هائلة.

يوفر بروتوكول Model Context Protocol (MCP) المطور من قبل Anthropic واجهة قياسية آمنة تعتمد على JSON-RPC 2.0 بين نماذج الذكاء الاصطناعي وقواعد البيانات. وعند دمجه مع منصة Supabase مفتوحة المصدر المزودة بمحرك pgvector ومجمع الاتصالات PgBouncer / Supavisor وسياسات أمان مستوى الصفوف (RLS)، يمكن للفرق بناء وكلاء قواعد بيانات يتمتعون بأعلى درجات الأداء والأمان.

2. الهندسة المعمارية: كيف يربط MCP بين النماذج وPostgreSQL

يفصل بروتوكول Model Context Protocol بيئة عمل الوكيل المضيف عن قاعدة البيانات من خلال عملية وسيطة خفيفة تتواصل عبر القنوات القياسية المحلية (stdio) أو عبر اتصال بعيد بتدفق أحداث الخادم SSE (HTTP/2).

+----------------------------------------------------------------------------------------------------+
|                                      HOST AI AGENT RUNTIME                                         |
|                       (Claude Code CLI, Cursor IDE, Windsurf, Custom Agent)                        |
|                                                                                                    |
|    +--------------------------+                                 +-----------------------------+    |
|    |    User Prompt Loop      |                                 |     Model Context Window    |    |
|    |  "Find top 10 users..."  |                                 | (System Prompt + MCP Tools) |    |
|    +------------+-------------+                                 +--------------^--------------+    |
|                 |                                                              |                   |
|                 | Dispatches Tool Call: execute_sql                            | Receives Schema / |
|                 v                                                              | Query Result Rows |
|    +---------------------------------------------------------------------------+--------------+    |
|    |                                      MCP CLIENT SUBSYSTEM                                |    |
|    |  - Capabilities Negotiation & Protocol Handshake (JSON-RPC 2.0)                          |    |
|    |  - Tool Call Serialization & Permission Policy Enforcement                               |    |
|    +---------------------------------------------+--------------------------------------------+    |
+--------------------------------------------------|-------------------------------------------------+
                                                   | Transport: stdio / SSE
                                                   v
+----------------------------------------------------------------------------------------------------+
|                                    SUPABASE / POSTGRES MCP SERVER                                  |
|                                                                                                    |
|    +----------------------+   +-----------------------+   +-----------------------------------+    |
|    | Schema Introspection |   | Read-Only Query Guard |   | pgvector Similarity Search        |    |
|    | - list_tables        |   | - AST parser / regex  |   | - semantic_search                 |    |
|    | - describe_table     |   | - statement_timeout   |   | - hybrid_search                   |    |
|    +----------+-----------+   +-----------+-----------+   +-----------------+-----------------+    |
|               |                           |                                 |                      |
+---------------|---------------------------|---------------------------------|----------------------+
                |                           |                                 |
                +---------------------------+---------------------------------+
                                            |
                                            v  Encrypted TLS Connection
+----------------------------------------------------------------------------------------------------+
|                                    SUPABASE POSTGRESQL INFRASTRUCTURE                              |
|                                                                                                    |
|    +------------------------------------------------------------------------------------------+    |
|    |                         SUPAVISOR / PGBOUNCER CONNECTION POOLER                          |    |
|    |  - Port 6543 (Transaction Mode) | Max 10,000 Client Conns | Shared Server Worker Pool    |    |
|    +----------------------------------------------+-------------------------------------------+    |
|                                                   | Internal Unix Socket / Local Loopback          |
|                                                   v                                                |
|    +------------------------------------------------------------------------------------------+    |
|    |                               POSTGRESQL 16/17 DATABASE ENGINE                            |    |
|    |  - Role: readonly_agent (NO DDL, SELECT only)                                            |    |
|    |  - Row Level Security (RLS) Policies                                                     |    |
|    |  - Extensions: pgvector, pg_stat_statements, pg_cron                                     |    |
|    +------------------------------------------------------------------------------------------+    |
+----------------------------------------------------------------------------------------------------+

الهندسة المعمارية: كيف يربط MCP بين النماذج وPostgreSQL - Core Responsibilities

الاستكشاف الديناميكي للمخطط: يطلب الوكيل بيانات الجداول المعنية فقط (list_tables وdescribe_table)، مما يمنع إهدار نافذة السياق في تعريفات غير ضرورية.
تنفيذ SQL محدد ومحمي: يتم حصر جميع الاستعلامات داخل معاملات آمنة مع فرض مهلة زمنية صارمة (statement_timeout = '5000ms').
بحث متجهي مدمج عبر pgvector: استعلام مباشر على فهارس HNSW وIVFFlat لتطبيقات RAG الهجينة دون الحاجة لقواعد بيانات متجهية خارجية.
عزل بيانات الاعتماد: لا يمتلك الوكيل كلمة مرور المدير العام، بل يعمل حصرياً عبر دور مخصص للقراءة فقط بصلاحيات مقيدة.

3. مقارنة الأداء المعياري: Supabase MCP مقابل PostgreSQL MCP وORM المباشر

أجرى فريق هندسة LLMPodium اختبارات إجهاد دقيقة لمقارنة ثلاثة أساليب ربط: خادم Supabase MCP الرسمي (@supabase/mcp-server-supabase)، وخادم المجتمع المفتوح لـ PostgreSQL، والتنفيذ المباشر عبر واجهة أوامر Prisma.

Benchmark Methodology

أجريت الاختبارات على مثيل Supabase Pro (معالجان vCPU وذاكرة 8 غيغابايت في منطقة AWS us-east-1) مع 50 جلسة متزامنة للوكلاء:

حمل العمل A (استكشاف المخطط): مسح طوبولوجيا 45 جدولاً علائقياً و280 مفتاحاً أجنبياً.
حمل العمل B (استعلامات تحليلية): تنفيذ 1,000 استعلام دمج وتجميع متعدد الجداول.
حمل العمل C (تزامن مكثف): 50 حلقة وكيل تنفذ عمليات قراءة في الوقت نفسه.

+-----------------------------------------------------------------------------------------------------------------------+
|                                    DATABASE AI AGENT ADAPTER BENCHMARK MATRIX (2026)                                  |
+-------------------------------------+------------------+-------------+-----------+-----------+------------+-----------+
| Adapter Implementation              | Transport Method | Schema TTFT | Query p50 | Query p99 | Max Conns  | Prompt KB |
+-------------------------------------+------------------+-------------+-----------+-----------+------------+-----------+
| Supabase MCP (Supavisor Pooler)     | stdio (Node.js)  | 28 ms       | 12.4 ms   | 48.2 ms   | 10,000+    | 1.8 KB    |
| Community PostgreSQL MCP            | stdio (TypeScript) 34 ms      | 14.1 ms   | 185.0 ms* | 90 (Cap)   | 4.2 KB    |
| Direct Agent via Prisma ORM CLI     | Subprocess Exec  | 142 ms      | 62.0 ms   | 240.0 ms  | 60 (Cap)   | 12.5 KB   |
| Remote SSE Supabase Gateway         | HTTP/2 SSE       | 86 ms       | 42.0 ms   | 110.0 ms  | 5,000+     | 2.1 KB    |
+-------------------------------------+------------------+-------------+-----------+-----------+------------+-----------+

Key Performance Findings

مجمع الاتصالات Supavisor ضرورة حتمية: سقط الاتصال المباشر عبر المنفذ 5432 فوراً تحت وطأة 50 اتصالاً متزامناً (FATAL: remaining connection slots are reserved). بينما تعامل Supabase MCP عبر المنفذ 6543 مع أكثر من 10,000 جلسة افتراضية باستقرار تام.
توفير هائل في رموز السياق: يستهلك Supabase MCP ما قدره 1.8 كيلوبايت فقط لتعريفات الأدوات مقارنة بـ 12.5 كيلوبايت عند حقن مخطط Prisma بالكامل.
زمن استجابة أقل من 15 مللي ثانية: لم يتجاوز العبء الإضافي للنقل المحلي عبر stdio حاجز 1 مللي ثانية، مما حافظ على سرعة المعالجة الأصلية لمحرك PostgreSQL.

4. دليل الإعداد خطوة بخطوة: Claude Code وCursor

يمكن تهيئة Supabase MCP للعمل مع Claude Code وCursor في أقل من خمس دقائق مع الالتزام التام بمبدأ الحد الأدنى من الصلاحيات.

المتطلبات المسبقة: إنشاء دور مخصص للقراءة فقط وضبط مهلة الاستعلام

-- 1. Create dedicated agent user role
CREATE ROLE agent_readonly WITH LOGIN PASSWORD 'SecureAgentPassphrase2026!';

-- 2. Grant connection rights to target database
GRANT CONNECT ON DATABASE postgres TO agent_readonly;

-- 3. Grant schema usage
GRANT USAGE ON SCHEMA public TO agent_readonly;

-- 4. Grant read-only access to existing and future tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON ALL TABLES TO agent_readonly;

-- 5. Revoke destructive permissions explicitly
REVOKE CREATE ON SCHEMA public FROM agent_readonly;
REVOKE ALL ON ALL SEQUENCES IN SCHEMA public FROM agent_readonly;

-- 6. Enforce statement timeouts (kills rogue queries after 5 seconds)
ALTER ROLE agent_readonly SET statement_timeout = '5000ms';
ALTER ROLE agent_readonly SET lock_timeout = '2000ms';

التكامل الأول: أداة Claude Code (CLI)

يدعم Claude Code خوادم MCP بشكل أصلي عبر أوامر سطر الأوامر أو ملفات التهيئة العامة.

#### Method 1: Interactive Terminal Command

# Add the Supabase MCP server via npx
claude mcp add supabase-db -- npx -y @supabase/mcp-server-supabase \
  --db-url "postgresql://agent_readonly:SecureAgentPassphrase2026!@aws-0-us-east-1.pooler.supabase.com:6543/postgres?sslmode=require"

#### Method 2: Global Configuration File

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ],
      "env": {
        "SUPABASE_DB_URL": "postgresql://agent_readonly:SecureAgentPassphrase2026!@aws-0-us-east-1.pooler.supabase.com:6543/postgres?sslmode=require",
        "SUPABASE_ACCESS_TOKEN": "sbp_your_personal_access_token_here",
        "SUPABASE_PROJECT_REF": "your-project-ref"
      }
    }
  }
}

التكامل الثاني: بيئة Cursor IDE

يدعم Cursor بروتوكول MCP مباشرة في الإعدادات (Features > MCP) أو عن طريق إضافة ملف .cursor/mcp.json في جذر المشروع.

{
  "mcpServers": {
    "supabase-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://agent_readonly:SecureAgentPassphrase2026!@aws-0-us-east-1.pooler.supabase.com:6543/postgres?sslmode=require"
      ]
    }
  }
}

5. الأمان المتقدم: بيئات العزل، تجميع الاتصالات وتفادي الحقن

يتطلب منح وكلاء الذكاء الاصطناعي صلاحيات الوصول لقواعد البيانات استراتيجية دفاعية متعددة الطبقات. لا تعتمد أبداً على التعليمات النصية البسيطة (مثل «يرجى عدم تعديل البيانات»).

+----------------------------------------------------------------------------------------------------+
|                                    DEFENSE-IN-DEPTH AGENT SECURITY LAYERS                          |
+-------------------+------------------------------------+-------------------------------------------+
| Defense Layer     | Mechanism                          | Threat Mitigated                          |
+-------------------+------------------------------------+-------------------------------------------+
| 1. PostgreSQL RBAC| Read-Only User Role (`agent_readonly`) Arbitrary DROP, INSERT, UPDATE, DELETE       |
| 2. Connection Pool| Supavisor / PgBouncer Port 6543    | Max Connection Exhaustion & Server Denial |
| 3. Execution Guard| `statement_timeout = '5000ms'`     | Infinite Loops & Cartesian Join Freezes   |
| 4. Client Boundary| Read-Only Toolset (`read_query`)   | DDL Execution via Parameter Injection     |
| 5. Query Auditing | `pg_stat_statements` + Access Log  | Stealth Exfiltration & Anomalous Scans    |
| 6. Data Isolation | Row-Level Security (RLS)           | Cross-Tenant Customer Record Exposure     |
+-------------------+------------------------------------+-------------------------------------------+

1. تجميع الاتصالات: المنفذ المباشر 5432 مقابل منفذ المعاملات 6543

ينشئ الوكلاء دفعات متتالية من الاتصالات القصيرة. يخصص المنفذ 5432 عملية نظام مستقلة لكل اتصال (5 إلى 10 ميغابايت ذاكرة)، مما يسبب انهيار الخادم سريعاً. في المقابل، يحرر مجمع المعاملات Supavisor على المنفذ 6543 الاتصال فور انتهاء الاستعلام، مما يتيح خدمة آلاف العملاء المتزامنين.

# ❌ NEVER use port 5432 for agent workflows in production:
# postgresql://user:pass@db.xyz.supabase.co:5432/postgres

# ✅ ALWAYS use port 6543 with transaction pooling:
# postgresql://user:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres?sslmode=require

2. التصدي لهجمات حقن SQL في مسارات عمل الوكلاء

يعد دمج السلاسل النصية مباشرة في الاستعلامات ثغرة خطيرة. في بيئات الإنتاج، استخدم محلل شجرة الإعراب النحوي (AST) للتحقق الصارم من السماح بأوامر SELECT وEXPLAIN فقط دون غيرها.

import { Parser } from 'node-sql-parser';

const parser = new Parser();

// ✅ SECURE: Strict AST parsing and parameterized inputs
export function validateAndExecuteReadOnlySQL(sql: string) {
  const ast = parser.astify(sql);
  
  // Enforce single-statement queries only
  if (Array.isArray(ast) && ast.length > 1) {
    throw new Error('Multi-statement execution rejected by security policy.');
  }

  const singleAst = Array.isArray(ast) ? ast[0] : ast;
  
  // Whitelist SELECT and EXPLAIN only
  if (singleAst.type !== 'select') {
    throw new Error(`Forbidden operation: ${singleAst.type.toUpperCase()}. Agent is read-only.`);
  }

  return true;
}

6. دراسة حالة عملية: وكيل تشخيص قواعد بيانات ذاتي القيادة

في منصة تجارة إلكترونية تعالج 10 ملايين معاملة، استطاع Claude Code عبر Supabase MCP تشخيص استعلام بطيء وإنشاء فهارس محسنة دون تدخل بشري:

Autonomous DBA Agent Execution Log

$ claude "Identify the 3 slowest queries in production from pg_stat_statements and check for missing indexes."

[Supabase MCP] -> Calling tool: execute_sql
Parameters: {
  "query": "SELECT query, calls, total_exec_time / calls AS avg_time_ms FROM pg_stat_statements ORDER BY avg_time_ms DESC LIMIT 3;"
}

[Supabase MCP] <- Result:
1. SELECT * FROM orders WHERE customer_id = $1 AND status = 'pending'; (avg_time_ms: 482.4ms, calls: 42,910)
2. SELECT * FROM order_items WHERE tracking_number = $1; (avg_time_ms: 312.1ms, calls: 8,400)
3. SELECT date_trunc('day', created_at), sum(total_amount) FROM orders GROUP BY 1; (avg_time_ms: 289.0ms, calls: 140)

[Claude Code Analysis]
Query #1 is an index scan bottleneck on 'orders'. Let me inspect current indexes on the 'orders' table.

[Supabase MCP] -> Calling tool: describe_table
Parameters: { "table_name": "orders" }

[Supabase MCP] <- Result:
Columns: id (uuid), customer_id (uuid), status (text), total_amount (numeric), created_at (timestamp)
Indexes: orders_pkey (PRIMARY KEY, btree, id)

[Claude Code Recommendation]
Found issue: Table 'orders' has NO index on 'customer_id' or 'status'. Sequential scan across 8,400,000 rows.
Recommended Remediation:
CREATE INDEX CONCURRENTLY idx_orders_customer_status ON orders (customer_id, status) WHERE status = 'pending';
Estimated query latency reduction: 482ms -> 1.4ms (99.7% improvement).

حدد الوكيل استعلاماً بطيئاً في pg_stat_statements يستغرق 482 مللي ثانية، وفحص هيكل فهارس الجدول عبر describe_table، ثم أصدر أمراً آمناً غير مانع للحظر CREATE INDEX CONCURRENTLY، مما قلص زمن الاستجابة إلى 1.4 مللي ثانية (تحسن بنسبة 99.7%).

7. تفصيل التكاليف وإجمالي كلفة الملكية (TCO)

تتوزع كلفة تشغيل وكلاء قواعد البيانات بين موارد استضافة البنية التحتية السحابية ورسوم رموز استدلال نماذج LLM:

+----------------------------------------------------------------------------------------------------+
|                               DATABASE AI AGENT INFRASTRUCTURE TCO (MONTHLY)                       |
+------------------------------------+--------------------------+------------------+-----------------+
| Component                          | Tier / Specification     | Usage Estimate   | Monthly Cost    |
+------------------------------------+--------------------------+------------------+-----------------+
| Supabase Pro Cloud Instance        | Compute: 2 vCPU, 8 GB    | 1 Production DB  | $25.00          |
| Supavisor Connection Pooler        | Built-in Managed Pooler  | 10,000 max conns | Included ($0.00)|
| pgvector Storage (Vector RAG)      | 15 GB NVMe Vector Data   | 2M embeddings    | Included ($0.00)|
| Claude 3.7 Sonnet Inference (Agent)| 120M Input / 18M Output  | 4,000 agent runs | $540.00         |
| DeepSeek V3 (Alternative Agent)    | 120M Input / 18M Output  | 4,000 agent runs | $21.84          |
| Hetzner Cloud VPS (Agent Host)     | CAX11 (2 vCPU, 4GB RAM)  | 24/7 Agent Daemon| $4.15           |
+------------------------------------+--------------------------+------------------+-----------------+
| Total Monthly Cost (Claude 3.7)    | Enterprise Tier          | 4,000 runs/mo    | $569.15         |
| Total Monthly Cost (DeepSeek V3)   | Cost-Optimized Tier      | 4,000 runs/mo    | $51.00          |
+------------------------------------+--------------------------+------------------+-----------------+

Key Economic Takeaway

من خلال الاستعانة بنماذج مفتوحة عالية الكفاءة مثل DeepSeek V3 أو Qwen 2.5 Coder لإجراء الفحوصات الروتينية، تنخفض التكاليف التشغيلية بنسبة أكثر من 90% (من 569 دولاراً إلى 51 دولاراً شهرياً) مع الحفاظ على نفس دقة التحليل.

8. الخلاصة وقائمة التحقق للمؤسسات

يوفر دمج Supabase مع Claude Code وCursor عبر Model Context Protocol دفعة غير مسبوقة لإنتاجية المطورين. احرص على تطبيق هذه القواعد عند النشر في الإنتاج:

التحكم الصارم في الوصول (RBAC): لا تمنح الوكيل صلاحيات المدير المطلق، واستخدم دائماً دور agent_readonly.
الاتصال دائماً عبر المنفذ 6543 (Supavisor): احمِ قاعدة البيانات من نفاد الاتصالات عبر تجميع المعاملات.
فرض مهلة زمنية صارمة: حدد statement_timeout = '5000ms' لإيقاف أي استعلامات جامحة.
فحص الاستعلامات عبر محلل AST: امنع أي عمليات تعديل للبيانات قبل وصولها إلى قاعدة البيانات.
المراقبة الدائمة عبر pg_stat_statements: راقب باستمرار جميع الاستعلامات التي ينفذها الوكلاء لتقييم كفاءتها.