Choose the API or MCP

The API and MCP can access overlapping Bily data and actions. The right choice depends on who controls the workflow and how repeatable it needs to be.

​

Choose by workflow

​

Use the API for repeatable software

Choose the API when your application owns the sequence. Use it for:

• scheduled analytics exports;
• store and account synchronization jobs;
• internal dashboards and reporting services;
• explicit create, update, toggle, clone, or delete workflows;
• integrations that need stable paths, request bodies, response schemas, and status codes.

API requests use the versioned base URL and server-side authentication. Your application controls retries, idempotency decisions, verification, and errors.

​

Use MCP for guided AI workflows

Choose MCP when a compatible AI client should interpret your intent and discover the current operation catalog. Bily MCP gives the client two stable tools:

• search finds supported Bily operations and their planning guidance;
• execute runs a focused async function with the selected bily.* helper.

Use it for:

• interactive questions about stores and analytics;
• exploratory work where the exact helper should be discovered at runtime;
• operator-reviewed actions where the client shows the complete execution before it runs;
• AI workflows that benefit from operation schemas, risk guidance, and verification hints.

MCP planning metadata is advisory. Keep the client approval visible. Verify every write with a read.

​

Combine surfaces when the workflow needs them

A complete implementation can give each surface one clear job: For example, the SDK sends product and order events. A backend job reads a daily analytics dataset through the API. An operator investigates the result through MCP.

​

Keep each surface in its role

• Do not place an API key in browser code.
• Do not use MCP as the website event transport.
• Do not use the browser SDK for scheduled server jobs.
• Do not call undocumented Bily endpoints when an OpenAPI operation exists.
• Do not hard-code MCP helper names without first using search for the current contract.

​

Compare the contracts

If an MCP investigation becomes scheduled production logic, move its repeatable work to the versioned API.