Terminal screen recording (asciinema+agg+ffmpeg, no AI-generated footage, no voiceover) of the real, unmodified code actually running: the 17/17 phpunit suite, scripts/verify-live.php against production api.scribase.com (real proof-of-work solve, real disposable-account retry, and a genuine 503 temporary_capacity response hit live during recording), the real bin/scribase-mcp-server stdio MCP server answering a real initialize/ tools/list handshake with all 5 tools, and a brief look at the real #[McpTool] attributes and Symfony AI Agent bridge wiring. demo/build.sh reproduces it deterministically from demo/raw/*.cast.
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
All the classes this example imports (Symfony\AI\Agent\Agent,
Symfony\AI\Agent\Bridge\Mcp\{ClientToolset,McpToolbox},
Symfony\AI\Platform\{Platform,Bridge\OpenAi\Factory}) were confirmed to
resolve against the real installed packages (composer require + a
class_exists() check against every one, not assumed from docs alone).
Honestly disclosed: this script needs a real OPENAI_API_KEY, an
owner-gated secret not configured in the environment this package was built
in, so unlike scripts/verify-live.php below, this one specific file has
been checked to compile and resolve against the real APIs but not run
end-to-end against a live LLM.
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 full live re-run then hit Scribase's own real, honest, global
capacity guard on free temporary projects (503 temporary_capacity — the
platform's own disclosed cap of 200 concurrently live anonymous/temporary
projects, shared across every real user and agent using it, not a flaw in
this code) before the fixed forget path could be re-confirmed end-to-end
against a second live project. The fix itself is not in doubt — Postgres's
own error message states the exact cast needed, and memory_id's
pre-validation makes the cast unconditionally safe — but re-run
scripts/verify-live.php yourself once the shared temporary-project pool
has headroom to see the complete, currently-green transcript for real. The
rest of the suite (steps 1–7, and store/recall/search/isolation within
step 8) is independently, already confirmed live and passing.
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.