SemiLayerDocs

MCP — MCP-ify anything

SemiLayer is an intelligence layer for any database. With the MCP integration, any AI agent becomes the interface to that intelligence layer — point it at a database you can already connect, and the agent turns it into a searchable, similar-able, feedable lens in the conversation.

One URL. Any MCP-aware agent. Any database.

https://mcp.semilayer.com/mcp

Add it to Claude Desktop, Cursor, Claude Code, or any agent that speaks MCP. Approve the OAuth consent once. The agent can now:

  • See every org, project, env, and lens you can access.
  • Build new lenses with one sentence — introspection, field typing, facet wiring, and access rules all scaffolded from the real schema.
  • Query your data — semantic search, similarity, typed filters, ranked feeds, per-record ranking breakdown.
  • Operate — run a smart sync, rebuild after a model change, pause indexing, watch status.
  • Collaborate — list, invite, and manage org members without leaving chat.

No API keys in your agent config. No long-lived secrets. Your role on each org controls what the agent can do.

Three turns, from zero to a ranked feed

Real transcript, Postgres with a recipes table + some ingest data:

❯ wire it up

quick_connect_lens introspected recipes, inferred id as PK from the schema, flagged title / description / cuisine / difficulty as searchable, wired search / similar / query with public rules. Dry-run showed the full shape; one "go" committed it.

❯ resume and add a discovery feed

resume_ingest un-paused the lens. add_facet auto-scaffolded discover into a recency-ranked feed (7-day half-life, 200 candidates, 12 per page, dedup on sourceRowId) and auto-attached rules.feed.discover = "public" so pk_ keys can hit it. Both committed.

❯ grab the first 5 items from that discovery feed

1. Mapo Tofu — chinese · medium · 30m
   "Silken tofu in a fiery Sichuan sauce with doubanjiang…"
2. Coq au Vin — french · hard · 180m
   "Chicken braised in red wine with lardons, pearl onions…"
3. Miso-Glazed Eggplant — japanese · easy · 15m
   "Broiled with a sweet-savory white miso + mirin + sake glaze…"
4. Shakshuka — middle_eastern · easy · 25m
   "Eggs poached in a spiced tomato-and-pepper stew…"
5. Green Curry with Tofu — thai · medium · 35m
   "Fragrant Thai green curry with coconut milk and Thai basil…"

Zero config files. Zero SDK boilerplate. The agent wrote the right config; the two-call confirm pattern kept you in the loop.

Why this is different

Most "AI integrations" pipe results into a chat. This is the inverse: the agent gets first-class access to your data plane with your identity. Every call flows through api.semilayer.com with a short-lived JWT signed server-side from your login session. RBAC, access rules, rate limits, quotas — all inherited.

  • Cross-scope natively. No "configure MCP for this org" — one connection, every org you belong to, pick any environment mid-conversation.
  • Safe writes. Destructive tools (quick_connect_lens, add_facet, update_lens_config, rebuild_lens, push, invite_member, …) are two-call: the first call returns a diff + a signed 15-minute token; the second commits. The agent cannot mutate without showing you the change first.
  • Hyper-aware tools. Add a new feed? The access rule attaches itself. Introspect a table? Field types flow from real column types. Ask about sync cadence? The tool descriptions carry the sync-approach cheat-sheet so the agent answers from vocabulary the platform actually enforces. Say "rebuild this lens" when it has 1,200 vectors? The tool renders a loud destructive-rebuild warning. Same tool on an empty lens? Calm "first build" narration.
  • Same meter as REST. MCP tool calls count against your existing API quota. No second bill, no second dashboard.

Auth, quickly

You → consent screen → back to your agent. That's the whole loop.

Click Connect in your agent

The agent fetches /.well-known/oauth-protected-resource from our server, discovers our authorization server, and dynamically registers itself as an OAuth client (no manual client-ID shuffling).

Our login provider hosts a consent page showing SemiLayer MCP as the target API and mcp:read mcp:write mcp:admin as the requested scopes. Same login you use for Console.

You're done

The agent gets a 1-hour access token, refreshed automatically (30-day rolling refresh). Revoke any time at console.semilayer.com → Settings → Sessions.

Zero static credentials anywhere. If you leave a project, your role changes, or you revoke the session — the agent's access evaporates on the next call.

Tool surface

ℹ️

Full catalog + arg shapes at MCP Tools. Below is the 30-second overview.

Explore (mcp:read) — whoami, get_map, set_context / get_context, list_lenses, describe_lens, list_members, status.

Query (mcp:read) — search, similar, query, feed, explain_feed (per-record score breakdown — similarity, recency, engagement, boosts).

Build (mcp:write, two-call) — quick_connect_lens (introspection → scaffolded lens in one turn), create_lens, update_lens_config (patch-merge with named-feed scaffolding + auto-rule attach), add_facet (named-facet merge; feed defaults by feed-name convention), push (full env reconciliation — the config-as-code path).

Operate (mcp:write, two-call) — resume_ingest (with first-build vs refresh hint), smart_sync (non-destructive scan + tombstone detect), rebuild_lens (context-aware — loud warning when vectors exist, calm first-build narration when empty), pause_ingest.

Admin (mcp:write, two-call) — invite_member, remove_member, edit_source.

Every write tool is two-call: first call → dry-run → { diff, confirm_token }; second call → { confirm_token } → commit. Tokens are 15-min one-shot opaque IDs (≤ 16 chars) so agents can echo them back verbatim.

Next