Skip to main content
Glama
Grona MCP

Grona MCP

by gbasilveira

Grona MCP

A TypeScript MCP server for all 10 operations in the captured Grona Public API contract, including the separate mobile grants API. It exposes 10 API tools plus 9 agent helpers, reference resources and reusable prompts over stdio. It uses the official MCP TypeScript SDK v2.

Campaign helpers support discovery, duplicate-safe creation, preview summaries, fresh installation checks, launch, A/B split updates, page-targeting simulation and snippet generation. Direct tools keep Grona's original response envelopes and extension fields.

Features

Direct API tools

Tool

Feature

grona_list_campaigns

List workspace campaigns.

grona_create_campaign

Create general or A/B campaigns with page targeting, optional visitor variables and traffic splits.

grona_get_campaign

Retrieve a campaign by Grona ID or external ID.

grona_update_campaign

Update supported campaign fields.

grona_delete_campaign

Permanently delete a campaign.

grona_set_campaign_status

Publish (live) or pause a campaign.

grona_create_edit_link

Generate a fresh visual editor link for a variation.

grona_validate_edit_link

Validate/refresh an existing editor link.

grona_verify_script

Check for the Grona installation snippet on a page.

grona_issue_grants

Request mobile grants for a customer using the separate mobile service and credential.

Workflow and local tools

Tool

Feature

grona_search_campaigns

Search names, IDs, external IDs and domains; filter campaign properties, sort and paginate locally.

grona_create_campaign_once

Create with a stable external ID, conservatively reconcile duplicate conflicts and refresh editor links on verified recovery.

grona_campaign_overview

Summarize campaign targeting, derived page URL, preview links, blockers and suggested next steps.

grona_check_campaign_readiness

Check usable variations, A/B split membership and fresh snippet presence; report blockers and manual checks.

grona_launch_campaign

Recheck readiness and publish after caller edit/preview attestations; report uncertain outcomes for reconciliation.

grona_set_ab_split

Resolve Control/Test variation IDs and set integer traffic percentages totaling 100%.

grona_evaluate_page_targeting

Locally simulate specific/multiple-page URL targeting, inclusion/exclusion rules and visitor-variable eligibility.

grona_generate_snippet

Generate escaped installation HTML, optional visitor-variable assignment and installation instructions.

grona_configuration

Report credential availability, endpoints, authentication mode, timeouts and retries without exposing secrets.

Reference resources

Resource

Contents

grona://reference/routes

API route-to-tool mapping.

grona://reference/agent-guide

Campaign lifecycle, targeting, installation, links and mobile guidance.

grona://reference/errors

Error codes, replay rules and recovery guidance.

grona://reference/openapi

Captured Grona OpenAPI specification.

Guided prompts

Prompt

Purpose

grona_campaign_lifecycle

Installation, creation, editing, preview and launch checklist; accepts an optional campaign ID.

grona_debug_installation

Diagnose snippet installation issues for a supplied URL.

grona_mobile_integration

Explain customer identity, separate credentials and grant handling obligations.

Prompts provide guidance; they do not perform API operations themselves.

Server capabilities

  • MCP stdio transport using the official TypeScript SDK v2.

  • Validated input schemas, JSON text and structured results, and tool annotations for reads, mutations and destructive actions.

  • Structured errors, recovery guidance and partial-workflow reporting.

  • Configurable endpoints, authentication mode, timeouts and retries, with separate Embed/mobile credentials.

  • Local tools and static reference resources usable without API credentials.

  • TypeScript exports for the server, client, configuration, schemas, workflows and types.

Related MCP server: Google Ads MCP Worker

Grona web app coverage

Public API coverage does not mean full web app coverage. The following describes this server against the API contract captured in this repository; it does not claim that no additional Grona APIs exist.

Web app section

MCP support

Home

No dashboard summary endpoint.

Recommendations

Not exposed.

Business

Not exposed.

Journey

Not exposed.

Website

Partial: generate installation snippets and verify snippet presence on a URL.

Campaigns

List, create, read, update, delete, publish/pause, editor links, preview summaries, readiness checks and A/B traffic splits. Visual editing happens in Grona's editor.

Site health

Partial: snippet verification only; no general site health reports.

Heatmaps

Not exposed.

Audiences

Partial: campaign targeting using page-variable names/values; no audience management or discovery.

Pages

Partial: campaign URL targeting and local targeting simulation; no page inventory or management.

Self-optimizing

No dedicated controls or results exposed.

Leads

Not exposed.

Analytics

Not exposed, including campaign performance and conversion metrics.

Integrations

No integration management.

Settings

Local MCP configuration diagnostics only; no Grona account/workspace settings management.

Mobile grant issuance is supported separately from these dashboard sections. The server does not perform visual edits, prove browser script execution, verify shopper identities or redeem grants. Snippet generation does not install it, and readiness checks still require manual browser checks. Supporting additional dashboard sections requires additional documented APIs or another authorized integration mechanism.

Run locally

Requires Node.js 22.12 or newer, npm and a Grona API key for network tools. Request an Embed workspace from Grona, then generate the workspace secret under Settings → Secrets. Mobile grants access and its key are provisioned separately by Grona.

npm ci
npm run build

Configure an MCP client to spawn the built executable. Replace the absolute path and configure secrets using the client's environment/secret settings:

{
  "mcpServers": {
    "grona": {
      "command": "node",
      "args": ["/absolute/path/to/grona-mcp/dist/index.js"],
      "env": {
        "GRONA_API_KEY": "your-embed-workspace-secret",
        "GRONA_MOBILE_API_KEY": "your-separate-mobile-secret"
      }
    }
  }
}

Omit GRONA_MOBILE_API_KEY if you only use Embed. See example client configuration. Local tools, resources and prompts work without credentials; an attempted API call reports which key is missing.

For direct launch from a shell with a protected local environment file:

cp .env.example .env
# Edit .env locally; never commit it.
node --env-file=.env dist/index.js

The process speaks MCP JSON-RPC on stdin/stdout and waits for a client; it does not print an interactive prompt. Environment files are loaded by Node's --env-file option, not implicitly by the server. The MCP client's env settings also work. To develop, use npm run dev.

Documentation

API coverage

HTTP method

Route

MCP tool

GET

/campaigns

grona_list_campaigns

POST

/campaigns

grona_create_campaign

GET

/campaigns/{campaignId}

grona_get_campaign

PATCH

/campaigns/{campaignId}

grona_update_campaign

DELETE

/campaigns/{campaignId}

grona_delete_campaign

PATCH

/campaigns/{campaignId}/status

grona_set_campaign_status

POST

/variations/edit-link

grona_create_edit_link

POST

/variations/edit-link/validate

grona_validate_edit_link

POST

/websites/verify-script

grona_verify_script

POST

/v1/mobile/grants on api.grona.ai

grona_issue_grants

Embed requests use https://services.grona.ai/api/public/v1. Mobile requests use https://api.grona.ai, always with the mobile credential. Workspace selection comes from each key, never from a tool argument.

Typical agent use

Start with grona_configuration and the workflow reference resource. Search existing campaigns before creating one. Use a stable business externalId with grona_create_campaign_once. Open the visual editor, save the changes, and check the preview. Then use readiness and launch helpers. New campaigns start paused.

The API exposes no analytics, campaign-result reports, visual-content editing, grant redemption, or key-management endpoints. The server does not invent those operations. Preview/editor links and mobile grants are sensitive; use only trusted MCP clients. See the Grona reference and operations guide.

Verify

npm run verify
npm run test:coverage
npm pack --dry-run

Tests exercise HTTP behavior through deterministic fakes/local services and MCP protocol calls through the official client. Production credentials are not required. Live Grona account behavior requires a provisioned workspace and is not claimed by these tests.

The verification record includes the final checks and live-account validation boundary.

Workorder management is bootstrapped from ~/trabalho/foundry-protocol, with the queue in docs/ORCHESTRATION.md and results under docs/work-orders.

Copyright (c) 2026 Guilherme da Silveira and contributors.

This implementation is free software under the GNU General Public License, version 3 or (at your option) any later version (SPDX: GPL-3.0-or-later). It is provided without warranty; see LICENSE.

The Foundry scripts are also licensed under GPL-3.0-or-later, with their original author attributions retained. Third-party dependencies retain their respective licenses, as recorded in package-lock.json.

Grona reference material in docs/upstream, including the proprietary API contract, is excluded from this GPL grant and remains subject to Grona's terms. Redistribution permission for that material must be established separately. This license grants no rights to Grona's service or branding.

Available Tools

19 tools
grona_campaign_overviewExplain campaignA
Read-onlyIdempotent

Read campaign and summarize targeting, previews, variation health and next steps. Does not mint editor links or claim analytics exist.

Inputs: campaignId (required). Returns: object

grona_check_campaign_readinessCheck launch readinessA
Read-onlyIdempotent

Read campaign and freshly verify its actual page from stored url or preview URL. Report observable blockers and manual checks. Cannot inspect saved edits or previews.

Inputs: campaignId (required). Returns: object

grona_configurationInspect configurationA
Read-onlyIdempotent

Show credential-presence flags, hosts and timeout/retry settings without secrets. Makes no upstream request.

Inputs: no named parameters. Returns: object

grona_create_campaignCreate campaignB

Create a paused campaign and variations with 15-minute editor links. Use externalId for duplicate protection. Requires Embed snippet and page variable. Creation never publishes.

Inputs: url (required), name (required), segmentId (required), segmentValue (required), +7 more. Returns: object

grona_create_campaign_onceCreate campaign onceB

Require externalId; on 409 fetch and compare existing campaign identity before recovering with fresh editor links. Conflict never patches or publishes an existing campaign.

Inputs: campaign (required). Returns: object

grona_delete_campaignDelete campaignA
Destructive

Permanently delete campaign and unshared variations. Frees externalId for reuse. Retry only by immutable Grona id. Propagation to visitors is asynchronous.

Inputs: campaignId (required). Returns: object

grona_evaluate_page_targetingSimulate page targetingB
Read-onlyIdempotent

Locally evaluate URL rules and optional page-variable value. Multiple-page exclusions still require exact origin and segment count. Predicts eligibility, not execution or traffic allocation.

Inputs: url (required), urls (required), list, slug, +6 more. Returns: object

grona_generate_snippetGenerate Embed snippetA
Read-onlyIdempotent

Generate escaped Embed HTML and optional page-variable assignment. Dashboard snippet may include anti-flicker; this helper installs nothing.

Inputs: workspaceId (required), segmentId, segmentValue. Returns: object

grona_get_campaignGet campaignA
Read-onlyIdempotent

Get by opaque Grona id or workspace-unique externalId. Grona id wins on ambiguity. No editor links return.

Inputs: campaignId (required). Returns: object

grona_issue_grantsFetch mobile grantsA
Read-onlyIdempotent

Fetch current signed grants from separate mobile service/credential. customerId must come from authenticated shopper session, never app input or PII. Return tokens unchanged; this does not verify or redeem them.

Inputs: customerId (required). Returns: object

grona_launch_campaignLaunch reviewed campaignA
Destructive

Require edited=true and previewed=true attestations, freshly verify actual campaign page, then set live by immutable id. Refuse absent snippet/unusable variations. Direct tools remain unguarded.

Inputs: edited (required), previewed (required), campaignId (required). Returns: object

grona_list_campaignsList campaignsA
Read-onlyIdempotent

Return every workspace campaign with variations and previews. No upstream pagination or specified order; editor links are omitted.

Inputs: no named parameters. Returns: object

grona_search_campaignsSearch campaignsA
Read-onlyIdempotent

Fetch full list once; filter locally by text/status/type/domain/script state/externalId and sort deterministically. offset/limit are local presentation controls.

Inputs: type, limit, order, query, +6 more. Returns: object

grona_set_ab_splitSet traffic split by roleA
Destructive

Read A/B campaign; map Control/Test to current variation ids, validate integer percentages total 100, update by immutable campaign id.

Inputs: Test (required), Control (required), campaignId (required). Returns: object

grona_set_campaign_statusSet campaign statusA
Destructive

Set live or paused. live affects real visitors after propagation. Prefer grona_launch_campaign for readiness guards; this direct route has none.

Inputs: status (required), campaignId (required). Returns: object

grona_update_campaignUpdate campaignA
Destructive

Patch mutable fields; returns full campaign. url/type/pageTargeting are fixed at creation. Retry only by immutable Grona id. trafficSplit keys are variation ids totaling 100.

Inputs: changes (required), campaignId (required). Returns: object

grona_verify_scriptVerify Embed installationA
Read-onlyIdempotent

Check exact page for this workspace’s Embed snippet. absent also means inaccessible page. Does not verify execution, anti-flicker, consent, CSP or whole site. Can take several seconds.

Inputs: url (required). Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, and the descriptions do unusually explicit boundary work (e.g. grona_launch_campaign vs grona_set_campaign_status, grona_verify_script vs grona_check_campaign_readiness). There are still overlapping read surfaces (list_campaigns / search_campaigns / get_campaign / campaign_overview) and two create paths, so a few pairs require reading descriptions carefully before selection.

    Naming Consistency4/5

    All tools share a grona_ prefix plus snake_case verb_noun naming (create_campaign, set_campaign_status, validate_edit_link, evaluate_page_targeting), which is highly predictable. The only deviations are noun-only names like grona_configuration and grona_campaign_overview, which break the verb pattern slightly but remain readable.

    Tool Count3/5

    At 19 tools the set sits at the heavy end for a campaign/experiment domain, with several near-siblings (two creates, four read variants, two status paths) that could arguably be consolidated. Each tool does have a defensible role, but the surface feels larger than the core workflow strictly requires.

    Completeness4/5

    Core lifecycle is well covered: create/get/update/delete/list/search, status and guarded launch, idempotent create, editor links, snippet generation and verification, A/B split, targeting evaluation, readiness and overview. The notable gap is results/analytics reading (explicitly out of scope) and no direct variation-content or variation-delete operation, though editor links provide a workaround.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading and mutating Google Ads campaigns via MCP tools, and includes structured marketer workflows for search term mining, budget optimization, and weekly reviews.
      6
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables management of Google Ads accounts via MCP, providing read and write tools for campaigns, ad groups, keywords, assets, and more, with support for reporting and mutations.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-capable agents to create, edit, pause, archive campaigns, and pull advertising reports from the Gravity Ads platform directly, without the API key leaving the local machine.
      17 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients to read and analyze Pinterest advertising data, with optional guarded write tools that preview changes before applying them, all while keeping your token on your own machine and protecting lead records.
      26
      374 npm
      Apache 2.0