@aurabase/mcp-server

Serveur MCP (Model Context Protocol) pour Aurabase — pilotez votre backend depuis Claude Desktop, Cursor, Windsurf, VS Code ou tout agent compatible MCP.

65 outils — 62 exposés avec une clé de projet, 3 réservés au plan de gestion. Protocole 2025-11-25, Node ≥ 20.

Principe

Un outil retourne la réponse du backend, ou une erreur. Jamais une valeur fabriquée.

Cette règle n'est pas une intention : elle est vérifiée à chaque exécution de la CI par deux bancs (bench/), dont l'un lance le serveur contre une URL morte et échoue si le moindre outil répond en succès. Chaque outil déclare de surcroît un outputSchema que le SDK valide avant d'émettre la réponse.

Installation

npx @aurabase/mcp-server \
  --url http://localhost:8080 \
  --project-id <uuid> \
  --service-role-key aura_sk_…

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "aurabase": {
      "command": "npx",
      "args": ["-y", "@aurabase/mcp-server"],
      "env": {
        "AURABASE_URL": "http://localhost:8080",
        "AURABASE_PROJECT_ID": "<uuid>",
        "AURABASE_SERVICE_ROLE_KEY": "aura_sk_…"
      }
    }
  }
}

Options

| Argument | Variable | Effet | |---|---|---| | --url | AURABASE_URL | URL de l'instance Aurabase | | --project-id | AURABASE_PROJECT_ID | Identifiant du projet | | --service-role-key | AURABASE_SERVICE_ROLE_KEY | Clé d'administration | | --read-only | AURABASE_READ_ONLY | N'expose que les outils de lecture (24 sur 65) | | --allowed-tools | AURABASE_ALLOWED_TOOLS | Liste blanche, séparée par des virgules | | --transport | — | stdio (défaut) ou http | | --port | — | Port du transport HTTP (défaut 3001) | | --host | — | Interface d'écoute HTTP (défaut 127.0.0.1) | | --auth-token | AURABASE_MCP_AUTH_TOKEN | Jeton exigé sur /mcp — obligatoire en mode http | | --no-auth | — | Démarre le mode http sans jeton, en l'assumant explicitement | | --allowed-origins | — | Origines autorisées en plus de localhost, séparées par des virgules | | --max-sessions | — | Sessions HTTP simultanées (défaut 32) | | --session-ttl | — | Expiration d'une session inactive, en secondes (défaut 1800) |

--read-only accepte true/false, 1/0, yes/no, on/off, ou le drapeau nu. Une valeur non reconnue empêche le démarrage plutôt que d'être interprétée comme « non ».

Mode lecture seule

Le mode retire tous les outils mutants du catalogue et demande à PostgreSQL d'exécuter le SQL dans une transaction en lecture seule (read_only sur /v1/db/{p}/raw). La garantie vient donc du moteur, pas seulement du filtrage côté client.

Transport HTTP

stdio reste le mode recommandé — la spec MCP le préconise et c'est celui qu'utilisent les clients locaux. Le mode http est disponible pour un usage distant ou partagé :

• écoute sur 127.0.0.1 par défaut ;
• exige un jeton (--auth-token) : sans lui, le serveur refuse de démarrer, --no-auth permettant de l'assumer explicitement ;
• valide l'en-tête Origin et répond 403 à une origine non autorisée, comme l'impose la spec — sans quoi une page web ouverte dans votre navigateur pourrait piloter ce serveur ;
• une instance de serveur par session, avec expiration et plafond ;
• /health n'expose aucune donnée de projet et n'est pas authentifié.

Outils

| Domaine | Outils | |---|---| | Base de données (19) | list_tables, execute_sql, query_table, insert_rows, update_rows, delete_rows, call_rpc, generate_types, diff_schema, apply_migration, explain_query, analyze_table, get_db_size, list_sql_functions, create_sql_function, drop_sql_function, list_sql_triggers, create_sql_trigger, drop_sql_trigger | | Storage (9) | list_buckets, get_bucket, create_bucket, list_files, delete_files, move_file, create_signed_url, upload_file, empty_bucket | | Auth (7) | list_users, get_user, create_user, update_user, delete_user, ban_user, generate_link | | Edge Functions (6) | invoke_function, list_functions, get_function_info, deploy_function, delete_function, set_function_env | | RLS (6) | list_rls_policies, create_rls_policy, update_rls_policy, drop_rls_policy, toggle_rls, get_security_advisors | | IA (5) | index_document, rag_query, vector_search, create_vector_index, ai_completion | | Notifications (4) | send_email, send_push_notification, send_sms, list_notification_logs | | Projet (4) | project_info, list_all_projects, switch_project, get_active_project | | Clés API (3) † | create_api_key, list_api_keys, revoke_api_key | | Observabilité (1) | get_project_metrics | | Realtime (1) | list_realtime_channels |

† Ces trois outils exigent le rôle administrateur du plan de gestion. Ils ne sont pas enregistrés avec une simple clé de projet — mieux vaut aucun outil qu'un outil qui échoue systématiquement.

list_sql_functions/create_sql_function/drop_sql_function et les outils *_sql_trigger créent de VRAIES fonctions/triggers PostgreSQL stockées dans le schéma du projet — sans aucun rapport avec list_functions/deploy_function (Edge Functions WASM, un runtime HTTP séparé). execute_sql/apply_migration refusent catégoriquement CREATE FUNCTION : ces outils sont le seul chemin qui en crée une réellement, appelable ensuite par call_rpc.

Ressource aurabase://schema (schéma complet du projet) et 4 prompts guidés sont également exposés. La ressource suit list_tables : elle disparaît si la liste blanche l'exclut.

Développement

npm install
npm test            # 88 tests unitaires
npm run typecheck
npm run build
npm run test:e2e    # nécessite une stack et RUN_E2E=true
node bench/mensonge.mjs   # aucun outil ne doit répondre en succès sans backend
node bench/effet.mjs      # chaque mutation prouvée par une lecture indépendante

Voir bench/README.md pour la méthode de mesure et ses pièges.

Licence

MIT — Aurabase