> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bily.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find and run MCP operations

> Use search and execute to choose current Bily operations, review risk, and return focused results.

Bily MCP exposes exactly two tools: `search` and `execute`. It does not expose MCP resources or prompts.

## `search`

Search the live Bily operation catalog before you construct an execution.

| Input      | Type    | Required | Behavior                                           |
| ---------- | ------- | -------- | -------------------------------------------------- |
| `query`    | string  | Yes      | Operation, action, or user intent to find          |
| `storeUrl` | string  | No       | Filters results using the accessible store context |
| `limit`    | integer | No       | Returns from 1 to 20 matches                       |

Example tool input:

```json theme={null}
{
  "query": "compare revenue with the previous period and explain the drivers",
  "storeUrl": "store.example.com",
  "limit": 8
}
```

Each result can provide:

* A stable operation ID, title, description, category, method, and Bily helper.
* Whether the operation requires a store or can write.
* Supported connected platforms when relevant.
* Planning metadata, including risk tier, approval policy, preconditions, verification, rollback hints, and input or output schemas.
* Focused usage examples.

The current catalog contains 64 operations: 45 read-oriented operations and 19 write operations.

## Confirm identity and scope first

Run the discovery helper before store-specific work:

```javascript theme={null}
async () => {
  return bily.context();
}
```

It returns the authenticated user and accessible `organizations[]`. Each organization's stores appear under `stores[]`.

Bily narrows a store-scoped fallback key automatically. With Bily Connect, add the optional `organizationId` input to `execute` only when the user explicitly selects one accessible organization.

## Explore operation families

| Family                   | Representative Bily helpers                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Identity and scope       | `bily.context()`, `bily.me()`, `bily.organizations()`, `bily.listStores(...)`                                                       |
| Store context            | `bily.getStoreData(...)`, `bily.getManagedAdAccounts(...)`                                                                          |
| Commerce reads           | `bily.shopify.graphql(...)`, `bily.shopify.rest(...)`                                                                               |
| Metrics and analytics    | `bily.analytics.getOverview(...)`, `bily.analytics.getRevenueTrend(...)`, `bily.analytics.queryDataset(...)`                        |
| Breakdowns and reports   | `bily.analytics.getProductMetrics(...)`, `bily.analytics.getCountryMetrics(...)`, `bily.analytics.getCohortMetrics(...)`            |
| Connected-platform reads | `bily.actions.getPlatformSupport(...)`, `bily.actions.listAssets(...)`, `bily.actions.listPixels(...)`                              |
| Supported actions        | `bily.actions.syncAdAccounts(...)`, `bily.actions.updateAsset(...)`, and the current creation or clone helpers returned by `search` |

Use this table as a map, not an exhaustive reference. Call `search` for the current helper signature and planning guidance.

## `execute`

Run one focused async arrow function with the helper returned by `search`.

| Input            | Type   | Required | Behavior                                                                 |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `code`           | string | Yes      | Async arrow function, at most 20,000 characters                          |
| `organizationId` | string | No       | Default organization for helper requests, subject to server scope checks |

Example tool input:

```json theme={null}
{
  "code": "async () => bily.context()"
}
```

The function can run for up to 20 seconds. It has no direct outbound network access.

Use `bily.*` helpers for Bily data and supported actions. Return JSON-serializable data.

A successful call returns:

```json theme={null}
{
  "result": {},
  "logs": [
    {
      "level": "log",
      "message": "optional captured output"
    }
  ]
}
```

Bily captures `console.log`, `console.warn`, and `console.error` in `logs`. A thrown error fails the tool call with its safe error message.

<Warning>
  Planning metadata guides the client and user. It does not replace a client approval prompt. Review the complete `execute` function before you approve any write.
</Warning>