Skip to main content
Glama

@beaconed/mcp

MCP server exposing the Beaconed v1 API to Claude Desktop, Cursor, and any MCP-compatible client. Ask Claude to list your products, queue optimizations, approve AI-generated copy, and manage webhooks — all via natural language.

Requires Node.js 22 or later.

Install

npm install -g @beaconed/mcp

Related MCP server: eonik-mcp

Setup

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "beaconed": {
      "command": "beaconed-mcp",
      "env": {
        "BEACONED_API_KEY": "your-api-key"
      }
    }
  }
}

Get your API key at beaconed.ai under Settings > API Keys.

Set BEACONED_BASE_URL to override the default https://beaconed.ai (useful for local dev or staging).

Tools

Read tools

  • beaconed_products_list — list products with filters for status, score, grade, and title search

  • beaconed_products_get — full product detail including images, score history, and latest optimization

  • beaconed_products_scores — score history for a specific product

  • beaconed_products_optimizations — list optimizations scoped to a product

  • beaconed_optimizations_list — list all AI-generated optimizations across all products

  • beaconed_optimizations_get — full optimization detail (original vs. suggested content)

  • beaconed_scores_list — readiness scores across all products

  • beaconed_scores_latest — latest score per product

  • beaconed_settings_get — account optimization settings (brand voice, keywords, auto-push config)

  • beaconed_webhooks_list — list webhook subscriptions

  • beaconed_webhooks_get — webhook detail including last error info

  • beaconed_webhooks_events — global catalog of all available webhook event types

Mutation tools

  • beaconed_products_create — create a product from external (non-Shopify) data

  • beaconed_products_update — update product fields (partial update)

  • beaconed_products_sync — refresh all products in the selected product’s shop from Shopify (rate limit: 10 requests/min)

  • beaconed_products_optimize — queue AI optimization for one or more product fields (rate limit: 10 requests/min)

  • beaconed_products_calculate_score — recalculate readiness score for a product (rate limit: 10 requests/min)

  • beaconed_optimizations_approve — approve a pending optimization; can publish live content when auto-push is enabled (rate limit: 10 requests/min)

  • beaconed_optimizations_reject — reject a pending optimization with an optional reason

  • beaconed_optimizations_apply — request application of an approved optimization to the live product (DESTRUCTIVE, rate limit: 10 requests/min)

  • beaconed_optimizations_revert — request reversion of an applied optimization to original content (DESTRUCTIVE, rate limit: 10 requests/min)

  • beaconed_webhooks_create — create a webhook subscription (signing secret returned once only)

  • beaconed_webhooks_update — update a webhook URL, events, or status

  • beaconed_webhooks_delete — permanently remove a webhook subscription (DESTRUCTIVE)

  • beaconed_webhooks_test — send a test event to verify delivery

  • beaconed_bulk_optimize — queue AI optimization for multiple products in one request (rate limit: 10 requests/min)

This package uses stdio and requires Node.js 20+. Tools operate on the account associated with BEACONED_API_KEY.

Optimization uses account credits; the request limit above is a rate limit, not a price. Queue acceptance does not confirm completion. Read product or optimization details to check the result. Approval can publish immediately or queue a Shopify write when auto_push_on_approve is enabled; inspect account settings and the proposed content before approving. Applying or reverting can replace live content.

Tool annotations describe read-only, replacement, repeat-call, and external-system effects. Clients may use these hints when asking for confirmation; the annotations do not enforce confirmation.

Hosted deployments must rate-limit POST /register at a trusted edge using the verified client address. The Node service deliberately ignores forwarded client-address headers because accepting them without an authenticated proxy boundary would let callers spoof the rate-limit identity.

The production container and required settings are documented in docs/deployment.md.

License

MIT — see LICENSE.

Registry publishing

server.json describes the stdio npm package. Its name matches mcpName in package.json; both versions must match the release being submitted. Publish and verify that exact npm version before running mcp-publisher publish. Registry acceptance and directory approval are separate from an npm release.

Available Tools

26 tools
beaconed_bulk_optimizeA

POST /api/v1/bulk_optimizations — queue AI optimization for multiple products in one request (queued, 202). EXPENSIVE: 10 req/min limit.

Inputs: product_ids (required), fields.

beaconed_optimizations_applyA
Destructive

POST /api/v1/optimizations/{id}/application — applies an approved optimization to the live product. DESTRUCTIVE: changes the product's public-facing copy. EXPENSIVE: 10 req/min limit.

Inputs: id (required).

beaconed_optimizations_approveA
Idempotent

POST /api/v1/optimizations/{id}/approval — approve a pending optimization, marking it ready to apply. EXPENSIVE: 10 req/min limit.

Inputs: id (required).

beaconed_optimizations_getA

GET /api/v1/optimizations/{id} — fetch full optimization detail including original and optimized content

Inputs: id (required).

beaconed_optimizations_listB

GET /api/v1/optimizations — list AI-generated optimizations with optional filters for status, field, product, and date

Inputs: page, field, since, status, +2 more.

beaconed_optimizations_rejectA
Idempotent

POST /api/v1/optimizations/{id}/rejection — reject a pending optimization with an optional reason.

Inputs: id (required), reason.

beaconed_optimizations_revertA
Destructive

POST /api/v1/optimizations/{id}/reversion — reverts an applied optimization back to the original content. DESTRUCTIVE: overwrites the product's current copy. EXPENSIVE: 10 req/min limit.

Inputs: id (required).

beaconed_products_calculate_scoreA
Idempotent

POST /api/v1/products/{id}/scores/calculation — recalculate the readiness score for a product. EXPENSIVE: 10 req/min limit.

Inputs: id (required).

beaconed_products_createA

POST /api/v1/products — create a product from external (non-Shopify) data. Use external_id for idempotency.

Inputs: tags, title, handle, images, +9 more.

beaconed_products_getB

GET /api/v1/products/{id} — fetch full product detail including images, score history, and latest optimization

Inputs: id (required).

beaconed_products_listA

GET /api/v1/products — list products with optional filters for status, score, grade, and search query

Inputs: q, page, grade, status, +4 more.

beaconed_products_optimizationsB

GET /api/v1/optimizations?product_id={id} — list optimizations for a specific product

Inputs: id (required), page, field, status, +1 more.

beaconed_products_optimizeA

POST /api/v1/products/{id}/optimization — queue AI optimization for one or more product fields (queued, 202). EXPENSIVE: 10 req/min limit.

Inputs: id (required), fields.

beaconed_products_scoresC

GET /api/v1/products/{id}/scores — fetch score history for a specific product

Inputs: id (required), page, grade, since, +2 more.

beaconed_products_syncA
Idempotent

POST /api/v1/products/{id}/sync — trigger a Shopify sync for the product (queued, 202). EXPENSIVE: 10 req/min limit.

Inputs: id (required).

beaconed_products_updateA
Idempotent

PATCH /api/v1/products/{id} — update a product's fields. Only include fields you want to change.

Inputs: id (required), tags, title, handle, +10 more.

beaconed_scores_latestC

GET /api/v1/scores/latest — fetch the latest score for each product (SPEC-ABSENT endpoint; verify availability with API team)

Inputs: page, grade, since, until, +1 more.

beaconed_scores_listA

GET /api/v1/scores — list readiness scores across all products (SPEC-ABSENT endpoint; verify availability with API team)

Inputs: page, grade, since, until, +1 more.

beaconed_settings_getA

GET /api/v1/settings — fetch the account optimization settings including brand voice, required/excluded keywords, and auto-push configuration

Inputs: no named parameters.

beaconed_webhooks_createA

POST /api/v1/webhooks — create a new webhook subscription. The signing secret is returned only once — store it securely.

Inputs: url (required), events (required).

beaconed_webhooks_deleteA
DestructiveIdempotent

DELETE /api/v1/webhooks/{id} — permanently remove a webhook subscription. DESTRUCTIVE: webhook deliveries stop immediately.

Inputs: id (required).

beaconed_webhooks_eventsA

GET /api/v1/webhooks/events — fetch the global catalog of all available webhook event types

Inputs: page, per_page.

beaconed_webhooks_getA

GET /api/v1/webhooks/{id} — fetch details about a specific webhook subscription including last error info

Inputs: id (required).

beaconed_webhooks_listB

GET /api/v1/webhooks — list webhook subscriptions registered for the current API key

Inputs: page, per_page.

beaconed_webhooks_testA

POST /api/v1/webhooks/{id}/test — send a test event to a webhook to verify delivery is working.

Inputs: id (required).

beaconed_webhooks_updateA
Idempotent

PATCH /api/v1/webhooks/{id} — update a webhook subscription's URL, events, or status.

Inputs: id (required), url, events, status.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools map cleanly to a resource and action, but a few boundaries are blurry: beaconed_products_optimizations and beaconed_optimizations_list both return optimizations (one filtered by product), and beaconed_products_get includes score history alongside beaconed_products_scores. These are workable but could cause occasional misselection.

    Naming Consistency3/5

    All names share the beaconed_ prefix and use snake_case, which helps, but the action pattern is inconsistent: most list operations use '_list' except beaconed_products_optimizations and beaconed_scores_latest, and noun/subresource ordering varies (products_scores vs scores_list). The naming is readable but not uniform.

    Tool Count2/5

    At 26 tools, the server is above the 25+ threshold and feels heavy for a single product-optimization domain. The webhook sub-surface alone accounts for 7 tools, and several product/optimization/score listing endpoints could be consolidated.

    Completeness4/5

    The optimization lifecycle (list/get/approve/reject/apply/revert) and webhook lifecycle (CRUD/test/events) are well covered, and score history plus latest scores are available. Obvious gaps are a settings update endpoint (only settings_get exists) and product deletion, but agents can still complete core workflows.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to manage Adobe Commerce and Magento 2 instances through business-level tools for catalog, promotions, CMS, and SEO. It features secure OAuth 1.0 authentication, safety guardrails for bulk operations, and built-in diagnostic reports for store health.
      38
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to connect to eonik and access brand assets, competitor research, and ad performance facts, while drafting creative briefs and scene breakdowns without spending or making changes.
      32
      634 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage Magento 2 / Adobe Commerce products, stock, orders, and customers through 12 read/write MCP tools with secure, audited access.
      AGPL 3.0