On Belay

MCP tool reference

Once Claude is connected over MCP, On Belay gives it a fixed set of tools — 14 of them. This is the complete reference: what each one does, what it takes, and what it returns.

Every tool runs inside your permissions. Claude can only reach the integrations your functional groups grant, and only the operations on each group's allowlist. Tools that read context return only what you're entitled to see. Nothing here lets Claude step outside your guardrails.

How to read this reference

Each tool is listed as a signature:

tool_name(required, optional?)

A trailing ? marks an optional parameter. Tool names, parameters, and field values are written in code. Tools are grouped by what they're for: setting up a session, discovering what's available, taking action, governance, and portfolio (agency/PE only).

Session & context

These tools load your org context into the conversation.

initialize_session(query?)

Call this first, once per conversation. It initializes the session and returns the integration domains you can reach (scopedDomains), the integrations available to you, and a sessionId. Pass an optional query — your initial question or intent — and On Belay pre-classifies which domains are relevant.

This is the instructed first call, but it is not technically enforced. The other tools work without it. Calling it first simply means Claude loads your accessible domains and integrations before it answers, so it acts with the right context from the start.

get_my_context()

Returns your functional group memberships, your Claude role, and your people guidelines. Call it after initialize_session to load full context. Takes no parameters.

get_group_context(group_name)

Returns the full context for one group by name — its Claude role instructions, strategy, and people guidelines. Use it to look up a specific team (for example, Marketing, Finance, or Owner) without loading every group you belong to, or to read a group you're not a member of.

Discovery

These tools help Claude find the right integration and operation before it acts.

list_my_integrations(clientOrgId?, verbose?)

Lists the integrations your groups have access to, with the permitted operations and a description of what each supports. This is how Claude learns which integrations are available and what's allowed.

  • clientOrgId? — for AGENCY and PE orgs only: filter to integrations delegated by one specific client. Get the orgId from list_my_clients.
  • verbose? — when true, include example queries per operation (this adds roughly 200 characters per operation). Defaults to false to keep responses compact for orgs with many integrations.

get_tools_for_domain(domain, sessionId?)

Returns every permitted operation for a domain. Domains look like MARKETING.EMAIL, FINANCIALS, or OPERATIONS.ORDERS, and prefix matching is supported — MARKETING matches all MARKETING.* subdomains. Pass the sessionId? from initialize_session to scope the results to your session.

get_tools_for_query(query, sessionId?, maxTools?)

Returns the operations most relevant to a natural-language query (for example, "Show email open rates" or "How much ad spend last month?"). Results are ranked by relevance. maxTools? caps how many come back (default 15); sessionId? is the session from initialize_session.

get_operation_schema(slug, key)

Returns full detail for one operation — its example path, example body, and usage notes — given an integration slug and an operation key. Call it before call_integration when you're unsure of the exact path or body. This is a catalog lookup: it reads the operation definition and does not require your org to have that integration connected.

Action

These tools do the work — calling APIs, reading cached data, and uploading content. All external calls run through the On Belay proxy, which holds credentials server-side.

get_integration_credential(slug)

Confirms that a credential exists for an integration. It does not return the API key — credentials are never exposed to Claude. Use it to verify access before calling call_integration. Pass the slug from list_my_integrations (for example, shopify, klaviyo, hubspot, stripe, slack).

call_integration(slug, operation, method, path, body?, query_params?, clientOrgId?)

Makes an authenticated API call to a third-party integration through the proxy. The proxy attaches the credential and returns the response — Claude never sees a raw key.

  • slug — the integration, from list_my_integrations.
  • operation — the operation key, from list_my_integrations or discovery.
  • method — one of GET, POST, PUT, PATCH, DELETE.
  • path — relative to the integration's base URL. Never a full https:// URL. It must match the operation's allowed path pattern.
  • body? — request body for POST/PUT/PATCH.
  • query_params? — query-string parameters as an object, e.g. { "limit": "250", "status": "any" }. Put them here, not appended to path.
  • clientOrgId? — for AGENCY and PE orgs working on behalf of a client.

A few rules worth knowing:

  • Only operations on your group's allowlist run. Calling a blocked operation returns an error explaining what to do next — it does not execute.
  • GraphQL integrations (Monday.com, Linear) always use POST with a body of { query: "...", variables: {} }. Use the path from the operation's schema; the proxy resolves the actual GraphQL endpoint.

query_cache(sql)

Runs a read-only SQL SELECT (or WITH) against your org's pre-seeded cache. It must start with SELECT/WITH — no INSERT, UPDATE, DELETE, DROP, or schema changes. The cache is fast and avoids API rate limits, so it's the preferred path for cached data; fall back to call_integration only when the cache has no rows or you need fresher data than the last sync.

Which tables exist depends on what your org has provisioned and synced. Common examples include shopify_orders, shopify_products, klaviyo_campaigns, klaviyo_flows, klaviyo_flow_metrics, klaviyo_email_daily, gsc_keywords, and gsc_pages. Every cached table includes org_id, a data (JSONB) column, and cached_at. If your org has no cache provisioned, the tool reports that there's nothing to query.

upload_to_youtube(video_url, title, description?, privacy_status?, tags?)

Uploads a video to the org's connected YouTube account. It downloads the file from video_url (mp4, mov, or webm) and uploads it via the YouTube Data API, returning the video ID and URL.

  • video_url — public URL of the source file.
  • title — the video title.
  • description?, tags? (comma-separated), and privacy_status? (unlisted, private, or public).

By default the video is uploaded as unlisted. This tool requires the YouTube integration to be connected to your org.

Governance

These tools record what Claude does and route anything that needs a human.

log_action(summary, outcome, integration?)

Writes an entry to your org's AI activity feed. Claude calls it after finishing significant work — querying an API, writing code, analyzing data, producing content — with a specific one-line summary (including key numbers). outcome is one of completed, failed, or pending_approval. integration? names the primary integration used, if any. This is how the org builds a record of what its AI actually did.

request_approval(action, analysis, risk_level, suggested_permission?)

When a user asks for something beyond their current permissions, Claude calls this instead of refusing. It files a formal approval request to the org's owners, who approve or deny it.

  • action — what the user is trying to do, in plain language.
  • analysis — why it needs approval, with a risk assessment.
  • risk_level — one of low (informational/read-only), medium (writes to internal systems), or high (external spend, data deletion, or security impact).
  • suggested_permission? — the permission change that would resolve this for good (for example, adding the person to a group or granting integration access).

Portfolio (agency / PE)

list_my_clients()

For AGENCY and PE org types only: returns the active client organizations that have approved a relationship with your agency, as [{ orgId, name, integrationCount }]. Pass a client's orgId as the clientOrgId parameter on call_integration (and list_my_integrations) to act with that client's delegated credentials. For other org types, this tool returns an error. There's no session-level "current client" — scope is set per call. See working as an agency or portfolio org for the full model.

Related

Questions about a tool's behavior? Reach us at hello@onbelay.ai.