Provides tools for interacting with the BigCommerce developer platform, including REST endpoints, webhooks, OAuth scopes, GraphQL APIs, code examples, and best practices for building on BigCommerce.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@erplinker/bigcommerce-mcp search for order webhook payload structure"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The complete BigCommerce developer platform as an MCP server — wired into Cursor, Claude, Windsurf, and any MCP-compatible AI tool.
Gives your AI assistant the knowledge of a senior BigCommerce Solutions Engineer. Instead of hallucinating API details, your AI calls this MCP server and gets precise, structured answers about every endpoint, webhook, auth pattern, GraphQL operation, OAuth scope, and code example in the BigCommerce developer ecosystem.
Coverage:
22 API categories — 171 fully-documented REST endpoints (v2 + v3)
42 webhook event scopes with payload field reference
21 OAuth scopes with read/write variants
3 GraphQL APIs — 30 operations (Storefront, Admin, Account)
12 MCP tools — search, endpoints, code gen, auth, best practices, live docs
49 live doc routes — fetches directly from developer.bigcommerce.com
Related MCP server: @prosodyai/mcp-docs
# Global install (recommended)
npm install -g @erplinker/bigcommerce-mcp
# Or local project install
npm install @erplinker/bigcommerce-mcpnpm install -g @erplinker/bigcommerce-mcpFind your binary path (you'll need this):
which bigcommerce-mcp
# macOS/Linux: /usr/local/bin/bigcommerce-mcp
# nvm users: ~/.nvm/versions/node/v20.x.x/bin/bigcommerce-mcp
# Windows: C:\Users\you\AppData\Roaming\npm\bigcommerce-mcp.cmdOpen the file at one of these paths:
macOS: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\mcp.json
Linux: ~/.config/cursor/mcp.json
Or via Cursor UI: Cmd+Shift+P → "Cursor: Open MCP Settings"
{
"mcpServers": {
"bigcommerce": {
"command": "bigcommerce-mcp",
"args": [],
"description": "BigCommerce full developer docs — REST, GraphQL, Webhooks, Auth, Stencil, Catalyst"
}
}
}Using nvm or non-standard PATH? Use the full absolute path:
{ "mcpServers": { "bigcommerce": { "command": "/Users/you/.nvm/versions/node/v20.18.0/bin/bigcommerce-mcp" } } }
No global install? Use npx:
{ "mcpServers": { "bigcommerce": { "command": "npx", "args": ["-y", "@erplinker/bigcommerce-mcp"] } } }
Fully quit and reopen Cursor
Open AI chat → type: @bigcommerce search for order webhooks
You should see the MCP tool execute and return structured data
If the tool doesn't appear, check View → Output → MCP in Cursor for error logs.
This is the key step. It tells Cursor's AI how to use the MCP tools like an expert.
Option A — Global (applies to all Cursor projects):
Cursor → Settings (Cmd+,) → Cursor Settings → Rules → "Rules for AI"Paste the contents of the Master Prompt section at the bottom of this README.
Option B — Per-project .cursorrules (recommended for BC projects):
Create a .cursorrules file in your project root and paste the Master Prompt from the section below.
Option C — New MDC format (Cursor 0.43+):
mkdir -p .cursor/rulesCreate .cursor/rules/bigcommerce.mdc and paste the Master Prompt from the section below.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"bigcommerce": {
"command": "bigcommerce-mcp"
}
}
}{
"mcpServers": {
"bigcommerce": {
"command": "bigcommerce-mcp",
"args": []
}
}
}Tool | Use When |
| Any BC question — searches endpoints, webhooks, GraphQL, scopes, best practices |
| Need all endpoints for a category (catalog, orders, customers, cart, etc.) |
| Need exact body schema, params, or OAuth scope for one endpoint |
| Need webhook scope names and payload structures |
| Setting up API accounts or app scopes — never guess these |
| Auth questions: REST, GraphQL tokens, Customer SSO, OAuth app flow |
| GraphQL queries, mutations, token setup |
| Need runnable code: REST calls, webhooks, OAuth, GraphQL, cart/checkout |
| Writing any loop or bulk operation — includes full production client |
| Architecture decisions: pagination, webhooks, apps, headless, performance |
| Debugging API errors (400, 401, 403, 404, 422, 429, 500) |
| Need live docs from developer.bigcommerce.com (49 available topics) |
"What endpoints do I need to build headless cart and checkout?"
"Write a Next.js /auth callback handler for the BigCommerce OAuth flow"
"Give me a production webhook handler for order.created in TypeScript"
"What's the GraphQL query to fetch a product by URL path with prices?"
"How do I sync 200k inventory records without hitting rate limits?"
"What OAuth scopes do I need for managing orders and customers?"
"How do I SSO a customer from my auth system into BigCommerce?"
"Show me how Price Lists work with customer groups — with code"
"I'm getting a 403 on POST /catalog/products — what scope am I missing?"
"Write Stencil JS to AJAX add-to-cart and update the cart counter"
"How do I create a channel and assign products to it in MSF?"
"Generate bulk inventory sync code with rate limit handling"You are an expert BigCommerce developer. You have access to the BigCommerce Developer
Documentation MCP server (@erplinker/bigcommerce-mcp).
ALWAYS call MCP tools before answering BigCommerce questions. Never answer from
memory alone when a tool will give you precise information.
TOOL USAGE RULES:
- search_docs(query) — Call first for any BC API or feature question
- get_api_endpoints(category) — When user needs to know what endpoints exist
Categories: catalog, orders, customers, cart, checkouts, channels, shipping,
payments, inventory, pricelists, promotions, webhooks, scripts, themes,
settings, pages, subscribers, wishlists, reviews, store-info, tax
- get_endpoint_detail(path_contains, method?) — For exact body/params/scope
- get_code_example(operation, language?) — Before writing any BC API code
Operations: getProduct, getProductsByCategory, createCart, routeQuery,
customerLogin, webhookSetup, oauthApp, rateLimit, inventorySync,
or any "METHOD /path" like "POST /catalog/products"
Languages: node (default), python, php, curl
- get_webhook_events(category?, search?) — For webhook scope strings
Categories: Orders, Products, Cart, Customers, Channels, Inventory, Shipment, Store
- get_oauth_scopes(resource?) — NEVER guess scope names. Always call this.
- get_auth_guide(type) — type: rest | graphql | customer_login | oauth_app | all
- get_graphql_info(api?, operation_search?) — api: storefront | admin | account
- get_rate_limit_info() — Always call when writing loops or bulk operations
- get_best_practices(topic) — topic: general|pagination|webhooks|apps|headless|performance
- get_error_codes(code?) — When user hits an API error, call this first
- fetch_live_doc(topic) — For niche or recently updated features
Topics: quickstart, about-api, authentication, api-accounts, oauth-scopes, catalog,
orders, customers, cart, checkouts, channels, shipping, payments, inventory,
pricelists, promotions, themes, scripts, settings, pages, subscribers, wishlists,
reviews, gift-certificates, graphql-storefront, graphql-admin, graphql-account,
webhooks, webhook-events, app-guide, app-callbacks, embedded-checkout,
customer-login, stencil, stencil-cli, catalyst, headless, storefront-tokens,
dev-portal, app-types, app-installation
ALWAYS IN GENERATED CODE:
- REST Management header: X-Auth-Token: {access_token}
(never use Authorization: Bearer for REST Management)
- GraphQL Storefront header: Authorization: Bearer {channel_token}
- Always include Content-Type: application/json and Accept: application/json
- Always handle 429: read X-Rate-Limit-Time-Reset-Ms, wait, retry
- Never put X-Auth-Token in client-side / browser JavaScript
- Show required OAuth scope in a comment above every API call
- Use ?include= query params to embed nested objects (avoid N+1 requests)
- Use bulk/batch endpoints for multi-record operations
- Use webhooks instead of polling the API
BASE URLS (always use these exactly):
- REST v3: https://api.bigcommerce.com/stores/{store_hash}/v3
- REST v2: https://api.bigcommerce.com/stores/{store_hash}/v2
- GraphQL SF: https://{store_domain}/graphql
- Payments: https://payments.bigcommerce.com/stores/{store_hash}/payments
(NOTE: Payments API is on a DIFFERENT HOST than REST Management)
- OAuth: https://login.bigcommerce.com/oauth2/token
ARCHITECTURE DECISIONS:
- Headless storefront → GraphQL Storefront API + Catalyst (Next.js)
- Store data management → REST Management API v3
- Real-time event handling → Webhooks (never polling)
- Customer SSO / sign-in → Customer Login API (HS256 JWT, 30s TTL)
- App Marketplace app → OAuth app (/auth + /load + /uninstall callbacks)
- Injecting JS to storefront → Scripts API (not manual theme edits)
- Customer-group pricing → Price Lists API
- Automatic cart discounts → Promotions API (not legacy Coupons)
- Multi-location inventory → Inventory v3 API with location_id
- Multi-storefront setup → Channels API + MSF architecture
ERROR HANDLING TEMPLATE (always include):
if (!response.ok) {
const error = await response.json();
throw new Error(`BC API ${response.status}: ${JSON.stringify(error.errors ?? error.title ?? error)}`);
}
RATE LIMIT TEMPLATE (always include for loops):
if (response.status === 429) {
const ms = parseInt(response.headers.get('X-Rate-Limit-Time-Reset-Ms') ?? '5000');
await new Promise(r => setTimeout(r, ms + 200));
// retry request
}
PAGINATION TEMPLATE (REST v3):
let page = 1;
do {
const res = await bc.get(`/endpoint?page=${page}&limit=250`);
// process res.data
page++;
} while (page <= res.meta.pagination.total_pages);bigcommerce-mcp/
├── src/
│ ├── index.ts # MCP server, all 12 tool handlers
│ ├── docs/
│ │ ├── knowledge-base.ts # 171 endpoints, 42 webhooks, 21 scopes, auth
│ │ └── fetcher.ts # Live doc fetcher → developer.bigcommerce.com
│ └── utils/
│ └── code-generator.ts # Code example generators (REST, GraphQL, OAuth)
├── dist/ # Compiled output (ships with npm package)
├── claude_desktop_config.example.json
├── package.json
├── tsconfig.json
├── LICENSE
└── README.mdMIT — see LICENSE
Fetch a live documentation page from developer.bigcommerce.com. Use when you need the most up-to-date documentation for a specific topic not covered by the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic slug to fetch. Available topics: quickstart, about-api, best-practices, authentication, api-accounts, oauth-scopes, catalog, orders, customers, cart, checkouts, channels, shipping, payments, inventory, pricelists, promotions, themes, scripts, store-info, settings, tax, wishlists, subscribers, pages, redirects, reviews, gift-certificates, coupons, graphql-storefront, graphql-admin, graphql-account, graphql-pagination, webhooks, webhook-events, app-guide, app-callbacks, embedded-checkout, customer-login, current-customer, stencil, stencil-templates, stencil-cli, catalyst, headless, storefront-tokens, dev-portal, app-types, app-installation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions 'live' but does not disclose what the output format is (HTML, text?), whether authentication is needed, or any rate limits. Lacks sufficient behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and source. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains purpose and usage context, but with no output schema, it should describe the return format (e.g., returns the full page HTML). Lacks completeness about output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the topic parameter, listing all available values. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch a live documentation page'), the source ('developer.bigcommerce.com'), and distinguishes from siblings by specifying 'not covered by the other tools'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('most up-to-date documentation for a specific topic not covered by the other tools'), implying when not to use (when other tools cover the topic). It provides clear context but could be more explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all REST API endpoints for a specific BigCommerce API category. Returns methods, paths, descriptions, required OAuth scopes, and parameter info.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | Filter by HTTP method: GET, POST, PUT, DELETE, PATCH | |
| category | Yes | API category slug. Options: catalog, orders, customers, cart, checkouts, channels, shipping, payments, inventory, pricelists, promotions, webhooks, scripts, themes, settings, pages, subscribers, gift-certificates, wishlists, reviews, store-info, tax |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description discloses the return fields but does not mention side effects, authentication requirements, or rate limits. However, the tool is clearly a read operation, which is implied by the name and description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no redundant information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With minimal parameters and no output schema, the description covers the main purpose and return fields adequately. It could be improved by mentioning output structure or pagination, but it is sufficient for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already describes both parameters. The description does not add new information beyond the schema, leading to a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves REST API endpoints for a BigCommerce category, listing the specific return fields. It distinguishes itself from sibling tools like get_endpoint_detail which likely targets individual endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the required category parameter but does not explicitly state when to use this tool over alternatives like get_endpoint_detail or fetch_live_doc. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get authentication guides and code examples for BigCommerce APIs — REST Management auth, Storefront GraphQL tokens, Customer Login API (SSO), and the OAuth app installation flow.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Auth type: rest (REST Management API), graphql (Storefront API), customer_login (Customer SSO JWT), oauth_app (App Marketplace OAuth flow) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it returns guides and examples but does not disclose output format, whether it requires authentication, or any side effects. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, concise and to the point without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers the purpose and available types. Could mention expected output format but not essential given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'type' fully described via enum and description. The description mirrors the enum values without adding significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Get authentication guides and code examples' and lists the exact auth types (REST, GraphQL, Customer Login, OAuth). Clearly distinguishes from sibling tools which cover endpoints, best practices, errors, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing auth guides, but provides no explicit guidance on when not to use it or alternatives among siblings like get_oauth_scopes or get_code_example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get best practices for BigCommerce development by topic area — pagination, webhooks, app development, headless/Catalyst, performance, and general API usage.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic area: general, pagination, webhooks, apps, headless, performance, or all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only lists topics and does not disclose behavioral traits such as read-only nature, idempotency, or any side effects. This is a significant gap for a tool that retrieves data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately communicates purpose and includes a comprehensive list of topics. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one enum parameter and no output schema, the description is mostly complete. It could mention what the response contains (e.g., list of practices), but the topic enumeration suffices for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% so the baseline is 3. The description adds natural language listing of topics, which mirrors the enum values but provides a bit more context. It does not add substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets best practices for BigCommerce development by topic area, listing specific topics. This distinguishes it from sibling tools like get_api_endpoints or get_code_example, which focus on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing best practices for a given topic, and the topic list provides clear context. However, it does not explicitly state when not to use this tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ready-to-use code examples for BigCommerce API operations in multiple languages. Includes REST API calls, GraphQL queries, webhook handlers, OAuth flow, cart/checkout, customer login, and more.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Programming language: node (default), python, php, curl | node |
| operation | Yes | Operation to get example for: getProduct, getProductsByCategory, createCart, routeQuery, customerLogin, webhookSetup, oauthApp, rateLimit, inventorySync, or specify a method+path like 'POST /catalog/products' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It implies a read-only retrieval operation by describing the tool as providing code examples, but does not explicitly state no side effects, rate limits, or authentication requirements. Adequate but not exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action and efficiently lists included categories. No wasted words, though the list could be more structured. Very concise for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters (well-described in schema) and no output schema, the description adequately covers the scope of examples. It does not discuss error handling or return format but the implied return (code snippets) is clear. Sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described, so baseline is 3. The description adds marginal context (e.g., types of examples) but does not significantly enhance understanding beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides 'ready-to-use code examples for BigCommerce API operations' and lists specific categories (REST, GraphQL, webhooks, OAuth, etc.), distinguishing it from sibling tools like get_api_endpoints (endpoint details) or get_auth_guide (auth only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. While the purpose is clear, it does not state 'use this for code snippets, use get_api_endpoints for endpoint details,' leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive detail for a specific BigCommerce API endpoint — request body schema, path parameters, query params, example response, OAuth scope, and usage notes.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | HTTP method: GET, POST, PUT, DELETE | |
| category | No | API category (e.g. catalog, orders, customers, cart) | |
| path_contains | Yes | Part of the endpoint path to search for, e.g. '/products', '/orders/{order_id}/shipments', 'variants' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool returns request body schema, path/query params, example response, OAuth scope, and usage notes. It does not mention side effects or auth requirements beyond scope, but for a read-only documentation lookup this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence packs maximum value with no wasted words. It is front-loaded with the action and resource, then lists deliverables concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and many sibling tools, the description sufficiently captures what the tool returns. It could mention whether matches are exact or partial, and if authentication is needed, but overall it is complete for a documentation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 3 parameters described). The description adds context that parameters relate to endpoint detail retrieval but does not exceed schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'comprehensive detail for a specific BigCommerce API endpoint'. It enumerates included elements (schema, params, example, OAuth scope, usage notes), clearly distinguishing it from sibling tools like fetch_live_doc or get_api_endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies the tool is for retrieving detailed endpoint info but does not differentiate from 12 sibling tools or advise on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get HTTP error code reference for BigCommerce APIs with explanations and troubleshooting guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Specific HTTP status code to look up, e.g. 422, 429, 403 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It discloses that the tool provides troubleshooting guidance, indicating a read-only, informative nature. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 13 words, front-loaded with purpose. Every word adds value. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with no output schema, the description is somewhat minimal. It lacks details on return format (e.g., list vs single object) and how the optional parameter affects output. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description for 'code' parameter. Description adds 'explanations and troubleshooting' but not specific parameter semantics beyond what schema provides. Baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and specific resource 'HTTP error code reference' with added value 'explanations and troubleshooting guidance'. Distinguished from siblings which cover different resources like auth, endpoints, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for looking up error codes, but no explicit when-to-use or when-not-to-use guidance compared to alternatives like get_api_endpoints or search_docs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about BigCommerce GraphQL APIs — Storefront API, Admin API, and Account API. Includes available operations, auth methods, and endpoints.
| Name | Required | Description | Default |
|---|---|---|---|
| api | No | GraphQL API name: storefront, admin, account, or all | |
| operation_search | No | Search for a specific operation by name, e.g. 'cart', 'product', 'route' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns information on operations, auth methods, and endpoints, implying a read-only operation. However, it lacks details on side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence states the purpose and scope, the second lists contents. No extraneous information, and the key details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two optional parameters and no output schema, the description adequately explains what will be returned. It covers the main contents (operations, auth methods, endpoints). Could mention response format more explicitly, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions in the schema. The description does not add extra meaning beyond the schema; it merely restates the API names. Thus, no added value beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves information about BigCommerce GraphQL APIs, listing three specific APIs and what is included (operations, auth methods, endpoints). It distinguishes itself from sibling tools like get_api_endpoints and get_endpoint_detail by focusing on GraphQL specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining GraphQL API information but does not explicitly state when to use it over alternatives or provide any exclusions. No guidance on when not to use this tool is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete OAuth scope reference for BigCommerce. Find the correct read/write scopes for any API resource.
| Name | Required | Description | Default |
|---|---|---|---|
| resource | No | Filter by resource name, e.g. 'products', 'orders', 'customers', 'payments', 'cart' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. States it retrieves a reference, implying a read-only operation. Simple and honest; no side effects are needed to be mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Front-loaded with the core purpose, then adds a benefit statement. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple reference tool. Could mention that the output is a list of scopes or that filtering is optional, but the current description is sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds examples ('products', 'orders', 'customers', 'payments', 'cart') that clarify the parameter's usage beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear description: 'Get the complete OAuth scope reference' with 'Find the correct read/write scopes for any API resource.' Distinguishes from sibling documentation tools by focusing specifically on OAuth scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit usage guidance: use when you need OAuth scopes for a resource. Does not explicitly state when not to use or compare to siblings, but the context of sibling names makes it reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get BigCommerce API rate limit details — how the bucket algorithm works, response headers, and a production-grade client with auto-retry and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| include_client_code | No | Include a full production-grade API client implementation with rate limit handling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the tool's output content (algorithm explanation, headers, client code). It indicates a read operation without side effects, though it does not specify whether the client is executable code or a code snippet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose and content. No unnecessary words, and the key action ('Get') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a documentation tool with one optional parameter and no output schema, the description adequately lists the types of information returned. However, it does not specify the format (text, code, structured data), which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (include_client_code) is fully described in the input schema. The tool description adds minimal extra context (e.g., 'production-grade'), not significantly enhancing understanding beyond the schema. Baseline is 3 due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves BigCommerce API rate limit details, including specific content like bucket algorithm, response headers, and a client implementation. This distinguishes it from sibling tools that cover other aspects of the API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when needing rate limit information, but it does not explicitly state when to use it versus alternative sibling tools like get_best_practices or get_code_example. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all BigCommerce webhook event scopes with descriptions and payload structures. Filter by category or search by name.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Search by event name or description keyword | |
| category | No | Filter by category: Orders, Products, Cart, Customers, Channels, Inventory, Shipment, Store, Catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as idempotency, rate limits, authentication requirements, or side effects. It implies a read operation but offers minimal behavioral context beyond the core function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the main purpose and filtering options. It is front-loaded and wastes no words, though slightly more structure could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions 'descriptions and payload structures' which provides useful return context. However, it lacks details on pagination, response format, or error handling. Fairly complete for a list-retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds 'Filter by category or search by name' which does not significantly enhance the schema-provided semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all BigCommerce webhook event scopes including descriptions and payload structures, and mentions filtering by category or search. This distinguishes it from sibling tools like get_api_endpoints or get_oauth_scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering options but does not provide explicit guidance on when to use this tool versus alternatives. There is no when-not-to-use or comparison with sibling documentation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across all BigCommerce developer documentation — API endpoints, webhooks, authentication, GraphQL, Stencil, Catalyst, best practices, and more. Use this as the first tool when you're not sure where to start.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default: 10) | |
| query | Yes | Search query, e.g. 'create product variant', 'webhook order created', 'customer login JWT', 'headless checkout' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Description only states it searches, omitting details like return format, pagination, or any required authentication. Lacks behavioral context beyond search capability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. First sentence defines purpose, second provides usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 2 params and no output schema, description covers scope and usage but misses return format (snippets, links) and potential limitations (e.g., no filtering). Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context about search scope (all BigCommerce docs) but does not elaborate on parameter behavior, such as how query is matched or limit usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs full-text search across all BigCommerce documentation, listing specific topics. It distinguishes itself from sibling tools by positioning as the starting point when unsure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this as the first tool when you're not sure where to start,' providing clear context. However, it does not explicitly exclude use cases or name alternative tools for known topics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1fetch_live_docget_api_endpointsget_auth_guideget_best_practicesget_code_exampleget_endpoint_detailget_error_codesget_graphql_infoget_oauth_scopesget_rate_limit_infoget_webhook_eventssearch_docsScored across 12 tools
Each tool has a clearly distinct purpose, ranging from fetching specific documentation pages to providing detailed endpoint info, error codes, and search. No two tools overlap in functionality.
Most tools follow a 'get_' prefix pattern, but 'fetch_live_doc' and 'search_docs' deviate. Otherwise, all names use lowercase snake_case and verb_noun structure, making them predictable.
With 12 tools, the server is well-scoped for a documentation-focused MCP. Each tool covers a specific aspect of BigCommerce developer resources without being excessive or too sparse.
The set covers major documentation areas (API endpoints, auth, best practices, code examples, GraphQL, OAuth, rate limits, webhooks, and search). While a few niche topics might be missing, search_docs provides a fallback.
100+ MCP tools for AI agents: content metadata, trade intelligence, business-expertise analysis.
327 dev tools via REST API and MCP. Generate Dockerfiles, schemas, K8s, APIs, and more.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Search, document and execute authenticated API calls across 700+ apps via one MCP server
