MCP Server¶

SLayer runs as an MCP server, allowing AI agents (Claude, Cursor, etc.) to discover and query data conversationally.

Quick Start¶

The fastest way to run SLayer is via uvx — no install needed. You only need uv.

Claude Code:

claude mcp add slayer -- uvx --from 'motley-slayer[postgres]' slayer mcp --ingest-on-startup

JSON config (Claude Desktop, Cursor, and other MCP-compatible agents):

{
  "mcpServers": {
    "slayer": {
      "command": "uvx",
      "args": ["--from", "motley-slayer[postgres]", "slayer", "mcp", "--ingest-on-startup"]
    }
  }
}

--ingest-on-startup runs idempotent auto-ingestion across every configured datasource before the stdio channel opens, so models are available on the agent's first tool call. Drop it (or set SLAYER_INGEST_ON_STARTUP=0) to defer ingestion to a manual ingest_datasource_models call.

Replace postgres with your database driver (see full list), or use motley-slayer[all] for all supported databases. SQLite and MCP work out of the box with the base install.

See the Getting Started guide for full setup instructions including SSE/remote and permanent install options.

Transports¶

SLayer supports two MCP transports. Both expose the exact same tools.

Stdio (local — recommended)¶

The agent spawns SLayer as a subprocess and communicates via stdin/stdout. You do not run slayer mcp manually — the agent launches it. The claude mcp add and JSON config examples above both use this transport.

SSE (remote)¶

MCP over HTTP via Server-Sent Events. You run slayer serve yourself — it exposes both the REST API and the MCP SSE endpoint on the same port:

uvx --from 'motley-slayer[postgres]' slayer serve --ingest-on-startup
# REST API at http://localhost:5143/
# MCP SSE at http://localhost:5143/mcp/sse

Then register the remote endpoint with your agent:

claude mcp add slayer-remote --transport sse --url http://localhost:5143/mcp/sse

This is useful when SLayer runs on a different machine, in Docker, or when multiple agents need to share the same server.

Verify¶

claude mcp list

Tools Reference¶

Datasource Management¶

Model Management¶

Querying¶

query parameters:

Memories + semantic search¶

Memories are free-form notes the agent saves against canonical entity strings (<ds>, <ds>.<model>, <ds>.<model>.<leaf>, or memory:<id>). search is the only retrieval surface and returns memories and entity discovery hits in one flat list. See Memories and Search.

search parameters:

Response shape (SearchResponse):

{
  "results": [
    {"kind": "memory",  "id": "42", "score": 0.13, "text": "...", "matched_entities": ["mydb.orders.amount"], "query": null},
    {"kind": "column",  "id": "mydb.orders.amount", "score": 0.11, "text": "...", "matched_entities": [], "query": null},
    {"kind": "model",   "id": "mydb.orders",        "score": 0.09, "text": "...", "matched_entities": [], "query": null}
  ],
  "resolved_input_entities": ["mydb.orders.amount"],
  "warnings": []
}

kind is one of "memory", "datasource", "model", "column", "measure", "aggregation". For memory hits, id is the raw memory id (suitable for forget_memory); hit.query is not None marks a saved example query. Column hits carry the column's structured sample-value snapshot — the top 50 sampled_values are rendered as a JSON array (so values containing commas survive), followed by Distinct count: N when the true cardinality exceeds the snapshot. SearchService refreshes any column hit whose profile is stale on the fly.

save_memory parameters:

forget_memory parameters:

Cypher filter examples. Naive form (always available):

MATCH (n:Memory) RETURN n.id AS id          # memory hits only
MATCH (n:Column:Measure) RETURN n.id AS id  # column + named-measure hits only

Full openCypher (requires advanced_search):

MATCH (d:Datasource {name: 'mydb'})-[:CONTAINS]->(m:Model)-[:CONTAINS]->(c:ModelColumn)
RETURN c.id AS id

Typical Agent Workflows¶

Connect and explore a new database¶

1. create_datasource(name="mydb", type="postgres", host="localhost", database="app", username="user", password="pass")
   # auto_ingest=true by default — models are generated automatically
2. models_summary(datasource_name="mydb")      # see what was generated
3. inspect_model(model_name="orders")          # see schema + sample data

To explore first without auto-ingesting:

1. create_datasource(name="mydb", type="postgres", host="localhost", database="app", username="user", password="pass", auto_ingest=false)
2. describe_datasource(name="mydb", schema_name="public")  # verify connection + list tables
3. ingest_datasource_models(datasource_name="mydb", schema_name="public")
4. models_summary(datasource_name="mydb")      # see what was generated

Query data¶

1. list_datasources()                              # pick a datasource
2. models_summary(datasource_name="mydb")      # discover its models
3. inspect_model(model_name="orders")          # see schema + sample data
4. query(source_model="orders", measures=["*:count"], dimensions=["status"], limit=10)

Customize a model¶

1. edit_model(
     model_name="orders",
     columns=[{"name": "priority", "sql": "priority", "type": "string"}],
     measures=[{"name": "aov", "formula": "revenue:sum / *:count", "label": "Average Order Value"}],
     remove={"columns": ["legacy_field"]}
   )

Upsert semantics: if a column/measure/aggregation/join with that name already exists, only the provided fields are updated. To remove entities, use the remove dict keyed by type ("columns", "measures", "aggregations", "joins"). measures here are named formulas ({formula, name, label, description}) — the row-level sql definitions live under columns.