Tool catalog

Eighteen tools. Read tools return data immediately. Write tools are two-call: first call returns a diff + signed confirm token; second call commits.

Every tool response pairs a content[] narration block (what you see in chat) with a structuredContent object (what the agent can render as tables/cards/etc).

Session context

Before listing tools, two conveniences that cut repetition: after set_context you can omit scope args on every other tool and they'll default from session.

set_context

Stash default orgSlug / projectSlug / envSlug / lensSlug for this session.

{ orgSlug?: string, projectSlug?: string, envSlug?: string, lensSlug?: string }

Empty string clears a level. Session-only — nothing persisted server-side.

get_context

Returns the current session defaults. Zero args.

Identity

whoami

Current caller identity. Zero args.

Returns user_card: email, platform-admin flag, orgs with roles, granted scopes.

Always safe to call first — tells the agent what it's allowed to do.

Navigation

get_map

The whole hierarchy in one call.

{
  scope?: 'orgs' | 'projects' | 'envs' | 'full',  // default 'full'
  include?: 'mappings',                            // inline full mapping configs (heavy)
  refresh?: boolean                                 // bust the cache
}

Returns map: orgs → projects → envs → lenses/sources/keys. RBAC-filtered at every level. get_map is the recommended first call for discovery — cheaper than iterating list_orgs → list_projects → list_envs.

list_lenses

Flat list of lenses with scope filter + substring match.

{ orgSlug?, projectSlug?, envSlug?, match?: string }

Returns lens_list. Each entry: { orgSlug, projectSlug, envSlug, name, status, facets }.

describe_lens

Full detail on one lens.

{ orgSlug?, projectSlug?, envSlug?, lens: string }

Returns lens_card: current config, declared facets, last-modified metadata, ingest runs. Required before most update_lens_config calls.

Data (read)

All take implicit scope from set_context if args are omitted. Role developer+ on the env gets sk-like access; viewer gets pk-like (rules enforced).

search

{
  orgSlug?, projectSlug?, envSlug?, lens?,
  query: string,
  limit?: number,   // default 10, max 100
  minScore?: number,
  mode?: 'semantic' | 'keyword' | 'hybrid'
}

Returns search_results. Same ranking as beam.<lens>.search().

similar

{
  orgSlug?, projectSlug?, envSlug?, lens?,
  recordId?: string,  // or...
  text?: string,      // ...one of the two
  limit?: number
}

Returns search_results ranked by vector similarity.

query

{
  orgSlug?, projectSlug?, envSlug?, lens?,
  where?: Record<string, unknown>,  // operator syntax — see Query docs
  orderBy?: Array<{ field: string; direction: 'asc' | 'desc' }>,
  limit?: number,   // default 50
  offset?: number
}

Returns query_results. Declarative filter/order — no free-text.

feed

{
  orgSlug?, projectSlug?, envSlug?, lens?,
  name: string,                       // named feed declared in the lens config
  context?: Record<string, unknown>,  // user-specific evolution context
  cursor?: string,
  limit?: number
}

Returns feed_page: items + cursor + live-update count.

explain_feed

{
  orgSlug?, projectSlug?, envSlug?, lens?,
  name: string,
  context?: Record<string, unknown>
}

Returns explain: per-scorer breakdown of feed ranking math. Read-only.

status

{ orgSlug?, projectSlug?, envSlug? }

Returns ingest_status: each lens in the env with its status, recent ingest runs, vector count.

Data (write)

All six tools below are two-call. First call = dry-run (returns diff + confirm_token). Second call = { confirm_token } and commits.

Every write carries destructiveHint: true so MCP clients that honor annotations will surface a confirmation prompt before your first call too.

create_lens

// First call:
{
  orgSlug?, projectSlug?, envSlug?,
  lens: string,           // name
  source?: string,        // source slug
  table?: string,         // table name
  config?: Partial<LensConfig>  // takes precedence over source/table/fields
}

// Second call:
{ confirm_token: string }

Creates a new lens in the env, paused by default. Call resume_ingest after.

update_lens_config

// First call:
{
  orgSlug?, projectSlug?, envSlug?, lens: string,
  patch: Partial<LensConfig>   // deep-merged into current config
}

// Second call:
{ confirm_token: string }

Server-side merge. Dry-run fetches current config locally to show you what changes.

add_facet

// First call:
{
  orgSlug?, projectSlug?, envSlug?, lens: string,
  facet: 'search' | 'similar' | 'feed' | 'dedup' | 'classify',
  config: Record<string, unknown>   // facet-specific
}

// Second call:
{ confirm_token: string }

For feed, the config key is { <feedName>: FeedFacetConfig }.

push

// First call:
{
  orgSlug?, projectSlug?, envSlug?,
  config: SemiLayerConfig,   // full config — create/update/delete to match
  resumeIngest?: boolean,
  rebuild?: boolean
}

// Second call:
{ confirm_token: string }

Mirrors semilayer push from the CLI. Commit response lists created/updated/deleted/unchanged lenses plus any ingest jobs queued.

pause_ingest

// First call:
{ orgSlug?, projectSlug?, envSlug?, lens: string }

// Second call:
{ confirm_token: string }

Pauses ingest. Existing vectors stay searchable.

resume_ingest

// First call:
{ orgSlug?, projectSlug?, envSlug?, lens: string }

// Second call:
{ confirm_token: string }

Resumes ingest on a paused lens.

Structured content kinds

Every response carries a structuredContent.kind that agents can render:

Clients that don't understand kind just render the JSON — still readable.

Limits

• Scopes: mcp:read, mcp:write, mcp:admin. Most tools gate on one; agents request the union of what they intend to use.
• Per-tool role requirements: viewer can call all read tools; developer+ required for data tools against rules-enforced lenses (same model as sk/pk). Write tools require developer+ on the target env.
• Rate limits: calls count against your org's existing API quota. No separate MCP meter. Your tier →.
• Response size: tool responses are capped server-side to stay within agent context budgets. Large get_map / query / search calls return a truncated view with a { truncated: true, remaining: N } hint.

Next

• Setup walkthroughs → — Claude Desktop, Claude Code, Cursor, Inspector
• Examples → — ready prompts