The 2026-11-07 video honestly showed scripts/verify-live.php hitting a real, disclosed production capacity limit mid-run (503 temporary_capacity) before scribase_memory_task's forget path could be captured green. That path is now fixed (previous commit) and re-confirmed live on 4 separate fresh production runs, so re-recorded demo/raw/02-verify-live.cast against a fresh run showing the full 9-step suite passing end-to-end, including store/recall/search/scope-isolation/forget and a real copy-on-write branch create+discard. Also fixed the end card's stale github.com/caelum0x URL to the real Rithub URL, and replaced the "hit a real production limit" caption with "3 real bugs found live, fixed, re-verified" to match what the new footage actually shows. Old partial-capacity-hit cast kept as a .bak rather than deleted. New video: 60.3s (was 52s), same 1920x1080 H.264 pipeline (demo/build.sh, ffmpeg-skill + asciinema/agg), no AI-generated or staged footage. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
scribase-mcp-php
A real Model Context Protocol server for
Scribase — 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 Agent via symfony/ai-mcp-tool.
Built for the Symfony AI & MCP 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
— 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. Usessymfony/http-client.src/SqlLiteral.php— encodes the handful of model-supplied stringsscribase_memory_taskever interpolates into SQL as a hex-encodedconvert_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'suuidcolumn needed fixing.src/ScribaseTools.php— the five#[McpTool]-attributed methods. Every parameter uses a native PHP type (string,?int,bool, …), somcp/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 viaServer::builder()->addTool(...).
Running the MCP server
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:
$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:
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+McpToolboxspawning this package's real MCP stdio server and listing its real tools over real MCP JSON-RPC — has been run live, not justclass_exists():php scripts/toolbox-check.phpprovisions 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$prefixparameter has no "disable prefixing" value — passing''(its own default) is the sentinel for<toolset-name>_, not an override — so every tool is listed asscribase_scribase_<tool>, doubled, since this package's own MCP tool names already start withscribase_. 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 — notclass_exists()alone, actual signature matches — but has not itself been run end-to-end against a live LLM call. Honestly disclosed: it needs a realOPENAI_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:
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 = (<literal>)::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:
- A
CREATE POLICYhidden inside aDO $$ ... $$block is invisible to Scribase's own migration linter.ensureMemoryTable()'s original DDL wrapped the RLS policy in aDOblock to make it idempotent (IF NOT EXISTS (SELECT ... pg_policies)). The linter — the same onescribase_lint_migration(tool #2) exposes, and whichdatabase/executeruns too — statically scans only a script's top-level statements forENABLE ROW LEVEL SECURITYpaired with aCREATE POLICY; it never looks inside aDOblock. So every memory-table bootstrap tripped the linter's ownmissing_rlsrule andscribase_memory_taskfailed withsql_blocked_by_lintbefore a single memory could ever be stored, on every project. Fix: makeCREATE POLICYa literal top-level statement. USING (true) WITH CHECK (true)trips the linter's ownpermissive_policyrule — correctly. Once the policy was visible, the literal predicatetrue/truetripped a second, legitimate rule: that predicate would authorise Supabase's public-facinganon/authenticatedroles 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.- A
DROP POLICY IF EXISTS, added to make fix #1 idempotent, was silently never executed at all.POST .../database/executeclassifies anyDROP .../DELETE ...statement as destructive and, without aconfirm: trueflag, replies{"status": "confirmation_required", ...}with HTTP 200 and noerrorkey — 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 inensureMemoryTable()'s own idempotency DROP, and independently inmemoryForget()'s plainDELETE— meaning every realforgetcall "succeeded" while deleting nothing, always reportingnot_foundeven for a memory that genuinely existed. Fix:ensureMemoryTable()now runs a cheap read-onlypg_policiesexistence check first and only ever submits the create/RLS/policy script once per project (so it needs noDROPat all);memoryForget()'sDELETE— already strictly scoped to one caller-suppliedidand the currentscope, the one case where auto-confirming a destructive statement is correct, since the caller's whole intent in callingforgetis that one delete — now sendsconfirm: true. Both paths also now check forconfirmation_requiredexplicitly rather than inferring success from the HTTP status alone, so this class of bug cannot hide silently again.
Run it yourself:
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
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_KEYis 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_querycannot write: the control plane rejects writes/DDL both lexically and inside a PostgresREAD ONLYtransaction, independent of this client.scribase_lint_migrationhardcodesapply: falsein this client's own code — never read from tool arguments — so this tool can only ever lint.scribase_memory_tasknever passes raw model-supplied SQL. Every interpolated value goes throughSqlLiteral::encode(), a hex-encodeddecode(...)expression that can only ever contain the ASCII characters0-9a-finside a plain single-quoted string — no quote, backslash, or comment sequence is representable, independent of the server'sstandard_conforming_stringssetting either way.
License
MIT.
Ecosystem
Part of the Scribase stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together.
- Scribase — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required
- Toolgate — one key for agent tools, pay only for what you call
- Scribase Mail — Resend-compatible email API
- More open-source projects from this account: git.ereboslab.com/caelum0x