# scribase-mcp-php A real [Model Context Protocol](https://modelcontextprotocol.io) server for [Scribase](https://scribase.com) — a hosted Postgres backend (Supabase/Neon alternative) — built on the **official PHP MCP SDK** (`mcp/sdk`, a PHP Foundation + Symfony collaboration) and wired into a real **[Symfony AI](https://ai.symfony.com) `Agent`** via `symfony/ai-mcp-tool`. Built for the **[Symfony AI & MCP Hackathon](https://symfony.com/hackathon)** (26 Oct – 22 Nov 2026). Every tool here calls Scribase's real, live, production management API (`api.scribase.com`) — nothing is mocked in the shipped code, and the "Real, live verification" section below is a genuine transcript from running this exact code against production, including one real bug it found and fixed. ## What it gives an agent Five tools, each backed by a distinct, real `api.scribase.com` endpoint: | Tool | What it does | Endpoint | |---|---|---| | `scribase_create_project` | Provisions a real hosted-Postgres project + environment, returns the connection string and API keys. | `PUT .../projects/{id}` + `POST /v1/environments` | | `scribase_lint_migration` | Runs Scribase's real migration-safety linter (missing RLS, permissive policy, `GRANT` to `PUBLIC`, `SECURITY DEFINER`, missing `WITH CHECK`, …). `apply` is hardcoded `false` in this client — it can only ever lint, never apply. | `POST .../migrations` | | `scribase_query` | One read-only SQL statement. The control plane enforces read-only twice, server-side (a static keyword check, then a Postgres `READ ONLY` transaction) — this client adds no write-guard of its own because none is needed. | `POST .../database/query` | | `scribase_branch_task` | A real copy-on-write Postgres branch per task: `create` (cut a branch from a parent environment), `promote` (three-way merge its schema back), `discard` (delete it). | `POST /v1/environments` (`kind: preview`), `POST .../branches/merge`, `DELETE .../environments/{id}` | | `scribase_memory_task` | Real, persistent agent memory — `store`/`recall`/`search`/`forget` — backed by a dedicated Postgres table (`hermes_agent_memories`) this tool creates on first use. Not a context window: a real row in the user's own database that survives across sessions. | `POST .../database/execute` (write-mode SQL) + `POST .../database/query` | This is the PHP/Symfony-native sibling of [`caelum0x/scribase-hermes-plugin`](https://git.ereboslab.com/caelum0x/scribase-hermes-plugin) — the same five tools, against the same production endpoints, built for Nous Research's Hermes Agent instead. Both clients wrap one real control plane; neither invents behavior the other doesn't have. The `hermes_agent_memories` table name is shared on purpose, so a project's stored memories are readable from either client. ## Architecture ``` ┌─────────────────────┐ tools/list, tools/call (JSON-RPC over stdio) │ MCP host │ ───────────────────────────────────────────┐ │ (Symfony AI Agent, │ │ │ MCP Inspector, │ ▼ │ Claude Desktop, …) │ ┌──────────────────────┐ └─────────────────────┘ │ bin/scribase-mcp-server│ │ Mcp\Server (mcp/sdk) │ └──────────┬───────────┘ │ addTool([$tools, 'method']) ▼ ┌──────────────────────┐ │ ScribaseTools │ │ (5 #[McpTool] methods) │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ ScribaseClient │ │ (Symfony HttpClient) │ └──────────┬───────────┘ │ HTTPS ▼ api.scribase.com (real, live, production) ``` - **`src/ScribaseClient.php`** — the HTTP layer: request/response, bounded operation polling (an unattended tool call can never hang forever), and reading back a ready environment's connection URI + API keys. Uses `symfony/http-client`. - **`src/SqlLiteral.php`** — encodes the handful of model-supplied strings `scribase_memory_task` ever interpolates into SQL as a hex-encoded `convert_from(decode('...', 'hex'), 'UTF8')` expression, never a classic quoted-and-escaped literal. See "Real, live verification" below for why, and for the one real bug this choice's `uuid` column needed fixing. - **`src/ScribaseTools.php`** — the five `#[McpTool]`-attributed methods. Every parameter uses a native PHP type (`string`, `?int`, `bool`, …), so `mcp/sdk`'s schema generator builds each tool's real JSON Schema straight from the method signature and docblock — no hand-written schema to drift from the code. - **`bin/scribase-mcp-server`** — the stdio entrypoint, wiring all five tools via `Server::builder()->addTool(...)`. ## Running the MCP server ```bash composer install SCRIBASE_API_KEY=sbk_... php bin/scribase-mcp-server ``` Point any MCP client at `php /absolute/path/to/bin/scribase-mcp-server` over stdio — the MCP Inspector, Claude Desktop's `mcpServers` config, or (below) a real Symfony AI `Agent`. ### Getting a real API key with zero login Scribase ships a genuinely free, no-account, no-card path for exactly this situation (an agent that needs a real project to test against): `POST /v1/temporary-projects` — solve a small proof-of-work, get a real org + project + production Postgres environment, and a real agent token scoped to just that project. It lives 72 hours unless claimed. This is the exact mechanism `scripts/verify-live.php` (below) uses. ## Using it from a real Symfony AI `Agent` `examples/symfony-ai-agent-demo.php` wires this server into a real `Symfony\AI\Agent\Agent`, using the official `symfony/ai-mcp-tool` bridge (`ClientToolset` + `McpToolbox`) — not a hand-rolled tool-calling loop: ```php $toolset = new ClientToolset( 'scribase', Client::builder()->setClientInfo('scribase-mcp-php-demo', '0.1.0')->build(), new StdioTransport(command: PHP_BINARY, args: [__DIR__.'/../bin/scribase-mcp-server'], env: ['SCRIBASE_API_KEY' => $scribaseKey]), ); $toolbox = new McpToolbox($toolset); $platform = new Platform([OpenAiFactory::createProvider($openAiKey)]); $agent = new Agent($platform, 'gpt-4o-mini', toolbox: $toolbox); $execution = $agent->call("Run a read-only query reporting the server time and database name."); echo $execution->asText(); ``` Run it: ```bash OPENAI_API_KEY=sk-... SCRIBASE_API_KEY=sbk_... \ SCRIBASE_ORG=tmp-... SCRIBASE_PROJECT=my-app \ php examples/symfony-ai-agent-demo.php ``` Verification status, precisely — two halves, checked to two different depths: - **The bridge half (no LLM needed)** — `ClientToolset` + `McpToolbox` spawning this package's real MCP stdio server and listing its real tools over real MCP JSON-RPC — **has been run live**, not just `class_exists()`: `php scripts/toolbox-check.php` provisions its own free temporary project and prints all 5 real tools, fetched from the real subprocess. It also surfaces a real, confirmed-live naming quirk: `McpToolbox`'s `$prefix` parameter has no "disable prefixing" value — passing `''` (its own default) is the *sentinel* for `_`, not an override — so every tool is listed as `scribase_scribase_`, doubled, since this package's own MCP tool names already start with `scribase_`. Harmless, but real. - **The agent-loop half (needs a real LLM)** — every constructor argument, named parameter and method call in `examples/symfony-ai-agent-demo.php` (`Symfony\AI\Agent\Agent`, `Symfony\AI\Agent\Bridge\Mcp\{ClientToolset,McpToolbox}`, `Symfony\AI\Platform\{Platform,Bridge\OpenAi\Factory}`, `Mcp\Client`) was checked against the real installed package source — not `class_exists()` alone, actual signature matches — but has **not** itself been run end-to-end against a live LLM call. **Honestly disclosed**: it needs a real `OPENAI_API_KEY`, an owner-gated secret not configured in the environment this package was built in. ## Real, live verification (not mocked) `scripts/verify-live.php` is not a unit test — it (1) solves Scribase's real proof-of-work challenge and provisions a real, free, no-login temporary project on **production** `api.scribase.com`, then (2) runs every one of this package's five tools — the literal, unmodified `ScribaseTools` class, zero monkeypatching — directly against it. Run it yourself: ```bash php scripts/verify-live.php ``` **A real run, 2026-11-07, found and fixed a real bug.** The first full run got through project provisioning, both migration-lint checks (blocked → clean), the read-only query, the rejected write, and four of `scribase_memory_task`'s five checks (`store` ×2, `recall`, `search`, scope isolation) — then `forget` failed with a genuine, reproducible Postgres error: ``` operator does not exist: uuid = text HINT: No operator matches the given name and argument types. You might need to add explicit type casts. LINE 2: delete from public.hermes_agent_memories where id = convert_from(decode('...', 'hex'), 'UTF8') and scope = ... ``` `hermes_agent_memories.id` is a real `uuid` column; `SqlLiteral::encode()` builds a `text`-typed expression (by design — see its docblock for why a hex-encoded literal is used instead of a quoted-and-escaped one), and Postgres has no implicit `uuid = text` comparison operator. **Fix**: cast the literal explicitly — `where id = ()::uuid` — safe here because `memory_id` is already validated against a strict UUID regex before this code path runs, so the cast itself can never fail on malformed input. Fixed in `ScribaseTools::memoryForget()`, covered by a regression test (`tests/ScribaseToolsTest.php::testMemoryForgetSendsAnExplicitUuidCastOnTheIdComparison`), and the real adversarial/non-ASCII test for `SqlLiteral` itself (`tests/SqlLiteralTest.php`) — ported from the same real re-verification methodology the companion Python plugin used to find its own, different, hex-encoding motivation (a backslash false-positive on ordinary non-English content, not an injection hole). **A second real run, 2026-11-17, found and fixed three more real bugs**, all in `scribase_memory_task`'s table-bootstrap and `forget` path, each only reachable once the `uuid` cast fix above let the suite get further than before. All three are fixed, and the full 9-step suite — every tool, `store`/`recall`/`search`/isolation/`forget`, a real copy-on-write branch create+discard — now passes end-to-end, live, against a fresh production temporary project: 1. **A `CREATE POLICY` hidden inside a `DO $$ ... $$` block is invisible to Scribase's own migration linter.** `ensureMemoryTable()`'s original DDL wrapped the RLS policy in a `DO` block to make it idempotent (`IF NOT EXISTS (SELECT ... pg_policies)`). The linter — the same one `scribase_lint_migration` (tool #2) exposes, and which `database/execute` runs too — statically scans only a script's *top-level* statements for `ENABLE ROW LEVEL SECURITY` paired with a `CREATE POLICY`; it never looks inside a `DO` block. So every memory-table bootstrap tripped the linter's own `missing_rls` rule and `scribase_memory_task` failed with `sql_blocked_by_lint` before a single memory could ever be stored, on every project. **Fix**: make `CREATE POLICY` a literal top-level statement. 2. **`USING (true) WITH CHECK (true)` trips the linter's own `permissive_policy` rule — correctly.** Once the policy was visible, the literal predicate `true`/`true` tripped a second, legitimate rule: that predicate would authorise Supabase's public-facing `anon`/`authenticated` roles too, were this table ever exposed through PostgREST (it is not — only this package's own direct, privileged connection ever touches it — but the policy should say that, not rely on it). **Fix**: deny those two roles by name (`USING (current_user NOT IN ('anon', 'authenticated'))`), allow everything else. 3. **A `DROP POLICY IF EXISTS`, added to make fix #1 idempotent, was silently never executed at all.** `POST .../database/execute` classifies any `DROP ...`/`DELETE ...` statement as destructive and, without a `confirm: true` flag, replies `{"status": "confirmation_required", ...}` with HTTP 200 and no `error` key — this client's original code checked only the HTTP status, so it read that as success and moved on, while the entire script (table creation included) had silently never run. This hit twice: once in `ensureMemoryTable()`'s own idempotency DROP, and independently in `memoryForget()`'s plain `DELETE` — meaning every real `forget` call "succeeded" while deleting nothing, always reporting `not_found` even for a memory that genuinely existed. **Fix**: `ensureMemoryTable()` now runs a cheap read-only `pg_policies` existence check first and only ever submits the create/RLS/policy script once per project (so it needs no `DROP` at all); `memoryForget()`'s `DELETE` — already strictly scoped to one caller-supplied `id` *and* the current `scope`, the one case where auto-confirming a destructive statement is correct, since the caller's whole intent in calling `forget` *is* that one delete — now sends `confirm: true`. Both paths also now check for `confirmation_required` explicitly rather than inferring success from the HTTP status alone, so this class of bug cannot hide silently again. Run it yourself: ```bash php scripts/verify-live.php ``` The rest of the suite (steps 1–7, the real copy-on-write branch in step 9) was independently confirmed live and passing before, during, and after this second round of fixes. ## Tests ```bash composer install composer test ``` 17 tests, 37 assertions, all passing: tool-argument validation (no network), real-response-shape replay tests (bodies captured verbatim from the live run above, including the `not_read_only` rejection and the `missing_rls` block), and two regression tests pinned directly to the real bugs found while building this package — the `uuid` cast above, and the pre-existing `ttl_hours: null` schema-validator rejection already known from the Python sibling's own history (this client omits the key entirely, never sends an explicit JSON `null`). ## Security notes - `SCRIBASE_API_KEY` is read once from the environment at server boot (`ScribaseClient::fromEnvironment()`) — never accepted as a tool argument, so a model can never read, exfiltrate, or rotate it through a tool call. - `scribase_query` cannot write: the control plane rejects writes/DDL both lexically and inside a Postgres `READ ONLY` transaction, independent of this client. - `scribase_lint_migration` hardcodes `apply: false` in this client's own code — never read from tool arguments — so this tool can only ever lint. - `scribase_memory_task` never passes raw model-supplied SQL. Every interpolated value goes through `SqlLiteral::encode()`, a hex-encoded `decode(...)` expression that can only ever contain the ASCII characters `0-9a-f` inside a plain single-quoted string — no quote, backslash, or comment sequence is representable, independent of the server's `standard_conforming_strings` setting either way. ## License MIT. ## Ecosystem Part of the [Scribase](https://scribase.com) stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together. - [Scribase](https://scribase.com) — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required - [Toolgate](https://toolgate.scribase.com) — one key for agent tools, pay only for what you call - [Scribase Mail](https://mail.scribase.com) — Resend-compatible email API - More open-source projects from this account: [git.ereboslab.com/caelum0x](https://git.ereboslab.com/caelum0x)