SignalQL MCP server

The @signalql/mcp package exposes SignalQL over MCP stdio for Cursor, Claude Desktop, and compatible hosts.

Tools

Tool	Purpose
run_signalql	Validate + compile; executes only when SQL is directly executable and DATABASE_URL is set
get_schema	Portable model metadata for prompts
list_events	Known event names for your demo/schema bundle
describe_event	Short description + sample properties

Run from npm

npx @signalql/mcp

Run from a local checkout

npm install
npm run build
npm exec -w @signalql/mcp -- signalql-mcp

Equivalent local command: node packages/mcp/dist/server.js.

Configure your MCP client to launch one of those commands. Logs go to stderr; stdout carries MCP frames only.

Safety

run_signalql uses @signalql/sdk compile path—parameterized SQL only. Execution uses bound parameters via postgres and is skipped for unresolved execution-plan SQL placeholders (v0.2 and v0.3 plan statements).

v0.5 Information Objects

• Object statements (GET OBJECT, FIND OBJECT, FIND DEPENDENTS, TRACE OBJECT, …) compile to direct SQL and execute like any other query.
• CONTEXT FOR "task" with execute: true runs the candidate SQL and then packs the rows into a context bundle; the response carries bundle with its context:// address. Bundles are kept for the life of the server process, so EXPLAIN CONTEXT context://… resolves them in the same session.
• SHOW CAPABILITIES and the get_capabilities tool return what the server supports without touching the database.

Run this query now

COUNT events FROM events WHERE event_name = "signup" DURING LAST 7 DAYS

Expected output shape: sql plus params from run_signalql; literal filters should be present as bound params.

Validation check: verify params is non-empty and SQL text contains placeholders instead of inline literal values.