# Gringo Funnels Remote MCP

Use the Gringo Funnels MCP to send a complete static page or multi-step funnel from an AI coding client into the signed-in user's Gringo Funnels workspace. The server creates the funnel, validates and stores every declared file, runs security/SEO/responsiveness quality gates, publishes an immutable release, enables first-party analytics, and returns its public URL.

## Canonical endpoint

https://gringofunnels.com/mcp

## Codex

```sh
codex mcp add gringo-funnels --url https://gringofunnels.com/mcp && codex mcp login gringo-funnels
```

The login command opens Gringo Funnels in the user's browser. The user signs in, selects the active workspace, reviews the exact permissions, and approves. No API key is copied into the agent. Once connected, a plain-language request such as “publish this page in Gringo Funnels” is enough.

## Claude Code

```sh
claude mcp add --transport http --scope user gringo-funnels https://gringofunnels.com/mcp
```

The command above installs the server URL; it does not authenticate it. Seeing
`Needs authentication` immediately afterward is the expected state.

1. Start Claude Code and run `/mcp`.
2. Choose `gringo-funnels`. If a previous attempt is stale, use **Clear
   authentication** first; then connect and finish the Gringo consent screen in
   the browser that Claude Code opens.
3. Wait for the browser to return to Claude Code's local callback, then return
   to Claude Code. `/mcp` should show the server connected and
   `publish_funnel` should be available. Try the current session first; if the
   client UI remains stale after it reports a successful connection, restarting
   Claude Code is a final client-side troubleshooting step.

Signing into `gringofunnels.com` in an unrelated browser tab does **not**
authenticate Claude Code. That website cookie can make the consent step faster,
but Claude Code must initiate the PKCE flow, receive its callback, and save its
own OAuth token.

If the browser finishes consent but its redirect reports that it cannot connect
to localhost, copy the full callback URL from the browser address bar and paste
it into the URL prompt waiting in Claude Code. This securely completes the same
PKCE exchange; do not copy an access token or authorization code by itself.

If `/mcp` still shows `Needs authentication`, use **Clear authentication**
for `gringo-funnels` inside `/mcp`, authenticate again, and let the callback
finish before closing the browser. Do not paste a token or edit credential files.

Use these read-only diagnostics outside Claude Code:

```sh
claude mcp get gringo-funnels
claude mcp list
```

`get` must show `https://gringofunnels.com/mcp`. `list` showing `Needs
authentication` means discovery succeeded but Claude Code has not stored an
OAuth token yet; it does not mean the Gringo MCP server is missing.

### Gringo sign-in versus MCP OAuth

Google, e-mail verification code, and password are all operational Gringo sign-in
methods. Google uses a dedicated production OAuth client and always shows the account
chooser. Whichever sign-in method you use, the website session remains separate from
the MCP OAuth token stored by the local client.

## Cloudflare Agents

Connect the Agent SDK MCP client to `https://gringofunnels.com/mcp` as a remote Streamable HTTP server. The same OAuth discovery flow opens Gringo Funnels, obtains the user's consent, and returns the connection to the agent. Do not paste a Gringo API key into a Worker.

## Any Streamable HTTP MCP client

Add a remote MCP server named `gringo-funnels` with URL `https://gringofunnels.com/mcp`. OAuth 2.1 discovery, PKCE S256, short resource-bound access tokens, Client ID Metadata Documents, and Dynamic Client Registration compatibility are available automatically. When the access token expires, the client opens the PKCE authorization flow again; refresh tokens remain disabled until replay-safe rotation is available.

## Gringo Funnels connection icon

The initialization response and registry descriptor advertise the Gringo Funnels
PNG icon from the same production origin. The browser consent page also displays
our brand and the website favicon. MCP clients choose whether to render server
icons; a terminal-only client may show the server name instead. Reconnect after
an update if the client has cached older metadata. The icon never requires a
cookie, token, or third-party image service.

## Publish a page

1. Ensure the page is a complete static bundle. Inline event handlers, inline scripts, remote scripts, `<base>`, and root-relative asset URLs are rejected.
2. Classify the work explicitly with `contentOrigin`: use `{ kind: "original" }` for original work, or provide the original funnel's bounded HTTPS URL, name, creator credit, and excluded deliverables for an educational recreation.
3. Generate one UUID `idempotencyKey` and call `publish_funnel` without an approval receipt. The server returns a release-bound review URL and opaque receipt. The OAuth grant is standing capability, not approval for a particular public release.
4. Ask the signed-in workspace administrator to open that URL, review the exact name, slug, provenance, manifest, file hashes and warning policy, and approve with fresh MFA. Source attribution cannot point to or deliver an excluded PDF, e-book, or webclass.
5. Retry the identical payload with the same `idempotencyKey` and the server-issued `approvalReceipt`. Never invent, reuse for another payload, or replace either value. If the response is ambiguous, call `reconcile_publish_funnel` with that same idempotency key; never issue a parallel publication.
6. For repositories larger than 6 MiB, use the resumable Gringo CLI/API upload path exposed in the account's Integrations page.
7. Check the returned status: only `published` confirms a live release and includes its release ID and live URL. A warning result preserves the funnel and upload and returns an exact `reviewUrl`. Open that signed-in review screen, inspect the warnings, and complete the same deployment. Do not call `publish_funnel` again with changed `allowWarnings` or a new key: that changes the approved action or creates another funnel. Remote OAuth MCP does not yet expose `complete_deployment`; that tool is currently available only in the local stdio adapter. For blocking checks, upload the corrected bundle into the existing funnel before reviewing it again.

## Claude Code funnel hacks and shared templates

Publishing through MCP creates a funnel in the connected workspace. It does
**not** add a template to the catalog for all users. Keep those two destinations
distinct when requesting an import.

For a funnel hack, preserve the source link and creator credit, provide original
Portuguese copy and replace third-party media, testimonials, logos, and offer
deliverables with assets you can distribute or explicit placeholders. A rewrite
alone is not a clearance check. Include your own breakdown video and explain
which sections customers need to customize.

The remote MCP supports uploading a scriptless static bundle and editing
existing V2 page/funnel documents with typed patches. It does not automatically
convert arbitrary HTML/CSS into native drag-and-drop blocks.

The platform owner can call `submit_shared_template_review` to submit an
exact owned release for the shared catalog. This needs an explicitly approved
`templates:submit` OAuth grant plus `funnels:write`; existing grants never
gain this permission automatically. Reconnect and review the added permission
before submitting. The tool returns a private review URL under
`/apxlbs-admin/shared-templates` and a pending submission, not a globally
published template. Poll the exact submission with
`get_shared_template_submission` after an ambiguous response, reusing the
same submission idempotency key when retrying.

The owner reviews the exact source declaration, redistribution rights, copy,
assets, breakdown video, preview and checksum. Publishing requires a separate
signed-in owner action with recent MFA. An MCP token or ordinary workspace
administrator role cannot publish a shared catalog entry. A submitted native V1 release becomes an editable native V1 template.
Native V2 templates preserve their complete editable page trees, rich text,
responsive styles and visibility. The current portable V2 subset is a linear
funnel using the builtin style guide, placeholder media and internal step links.
Tenant media, external destinations, experiments, commerce, workflows and
reusable-component bindings return an explicit unsupported-dependency error;
there is no silent V1 downgrade. Clones get new workspace-owned page, form and
graph IDs, verified checksums and disabled search indexing until publication.
A supported static release of no more than 6 MiB remains a code-managed template.
Neither path converts HTML into native blocks.

Use `list_shared_templates` with `funnels:read` to discover approved catalog
entries. Customers open Templates in their signed-in workspace and choose an
approved version to create a private draft with new workspace-owned IDs.
Direct MCP draft instantiation is not available: existing MCP publication
approval boundaries remain in force. Using a template in the browser never
publishes a page, connects a domain, or activates copied integrations. Any later
public release uses its own publication review and approval.

Do not tell the user a workspace publication is a shared template, and do not
attempt to work around the owner boundary with another workspace or API key.

## Local stdio MCP and CLI

Clients that support Streamable HTTP with OAuth should use the remote endpoint
above. The repository also includes `tools/gringo-mcp.mjs`, a local stdio
adapter for `list_funnels`, `create_funnel`, `deploy_funnel_bundle`,
`get_deployment`, and `complete_deployment`. It requires an existing scoped `GRINGO_API_KEY` supplied
through the client's protected environment. Its tool catalog is smaller than
the remote server's; it is not a drop-in replacement for the V2 authoring tools.

If an uploaded deployment requires warning review, inspect its quality report,
then call `complete_deployment` with the returned funnel and deployment IDs.
Set `allowWarnings: true` only after reviewing those warnings. Completion
reuses the existing upload; repeating `deploy_funnel_bundle` with
`createName` would create another draft. Quality blocks still require a fixed
bundle, and cannot be overridden by warning confirmation.

For a larger static repository, use the downloadable CLI described in the
Integrations page. Neither the CLI nor stdio adapter submits a shared template;
use the remote OAuth MCP for the owner-attributed review workflow. API keys
cannot request `templates:submit`. Keep secrets out of prompts and committed
config files.

## Tool catalog

Site tools reuse the existing `funnels:read` and `funnels:write` permissions.
Connections authorized before version 1.1 must be reconnected before any domain
tool so the user can explicitly approve `domains:write`.
Shared-template submission introduced in version 1.4 requires a new explicit
`templates:submit` grant; authoring and publishing permissions alone do not
authorize it. Catalog reads use `funnels:read`; draft creation from shared
templates uses the signed-in browser, not an MCP tool.

- `list_funnels`: read the current workspace's funnels and publication state.
- `publish_funnel`: consequential external publication. The first call creates a five-minute exact-action review request. Fresh MFA approval is valid for at most two minutes and is consumed once. The same idempotency key returns one stable result.
- `reconcile_publish_funnel`: inspect and durably settle the exact prior publication after a timeout. It never creates another funnel or release.
- `get_deployment`: inspect upload, quality, and release status.
- `get_funnel`: inspect ordered steps, releases, domains, and experiments for one funnel.
- `change_funnel_status`: pause, reactivate, return to draft, or archive one exact funnel with a current-state precondition and explicit confirmation. This preserves releases and analytics and is the cleanup step for acceptance canaries.
- `list_sites`, `get_site`, `create_site`, `update_site`: organize related published content under one Site namespace.
- `mount_funnel`, `update_site_mount`, `unmount_funnel`: mount a funnel, listicle, quiz, or standalone page at `/`, `/offer`, `/quiz`, and other safe Site paths. The most-specific path wins. Adding or changing routes on a Site with any attached domain requires an active custom-domain entitlement; unmounting remains available, except that a domain-anchor route must keep its domains or have them removed first.
- `list_site_domains`, `connect_site_domain`, `rotate_site_domain_claim`, `refresh_site_domain`, `remove_site_domain`: manage a Site hostname and its exact DNS/TLS state. Rotate only when a pending one-time TXT value was lost or expired. Connect, rotate, and refresh require an active custom-domain subscription; a missing entitlement returns the machine-readable `402 subscription_required` error and never changes DNS. Removal remains available so a customer can always stop serving a hostname.
- `connect_domain` and `refresh_domain`: legacy funnel-domain facades retained for existing automations. New integrations should always use the Site-domain tools.
- V2 page tools: `get_page_document_v2`, `upgrade_page_document_v2`, `patch_page_document_v2`, and `checkpoint_page_document_v2`. Patches are bounded typed commands at an exact revision; a whole-document overwrite tool does not exist.
- V2 funnel and experiment tools: `get_funnel_graph_v2`, `upgrade_funnel_graph_v2`, `patch_funnel_graph_v2`, `list_step_experiments_v2`, `get_step_experiment_v2`, `create_step_experiment_v2`, and `patch_step_experiment_v2`. MCP can create and edit experiment drafts but cannot start traffic or choose a winner.
- V2 workflow tools: `get_workflow_graph_v2`, `upgrade_workflow_graph_v2`, `patch_workflow_graph_v2`, and `compile_workflow_v2`. Compile is validation-only and never activates delivery.
- V2 commerce tools: `list_commerce_bindings_v2`, `get_commerce_binding_v2`, `create_commerce_binding_v2`, and `patch_commerce_binding_v2`. They bind approved catalog/policy versions in draft state and never expose provider credentials or enable live checkout.
- V2 release tools: `validate_v2_patch`, `list_funnel_releases_v2`, `get_funnel_release_v2`, `diff_funnel_release_v2`, `compile_funnel_release_v2`, `get_funnel_preview_v2`, `publish_funnel_release_v2`, `rollback_funnel_release_v2`, and `reconcile_funnel_release_v2`. Validation is read-only, compilation creates an immutable non-public candidate, and preview returns only the signed-in workspace URL. Publish and rollback first return an exact review URL; a signed-in administrator must approve that checksum with fresh MFA, and the same idempotency key and single-use receipt must be replayed. On ambiguity, reconcile the same operation/key; never submit a parallel action. OAuth scope or `confirm: true` is never sufficient.
- Shared-template tools: `submit_shared_template_review`, `get_shared_template_submission`, and `list_shared_templates`. Submission is owner-only and queues an exact release for separate browser review; only approved versions appear in the catalog. Customers use approved native or code-managed templates through the browser Templates screen.
- Prompt `publish-current-project`: reusable instructions for packaging the current repository.

## Minimal prompt

> Install and connect the Gringo Funnels MCP, determine whether this work is original or an educational recreation, prepare the exact publication payload, and request its server-issued approval URL with one UUID idempotency key. Wait for me to approve that exact digest with MFA, then retry the identical payload with the returned receipt. On timeout reconcile the same key; never create a parallel publication. Return the live URL plus quality report.

## Organize one domain without duplication

Create one Site for each hostname namespace, then mount existing content beneath
it. For example, a primary sales funnel can remain at `/`, a listicle at
`/reviews`, and a quiz at `/quiz`. DNS points only a hostname at Gringo;
it never controls individual paths. This means a hostname that already serves a
different website should normally use a subdomain (for example,
`offers.example.com`) unless Gringo is intended to own the whole hostname.

1. Call `create_site`.
2. Publish or select funnels with `publish_funnel` / `list_funnels`.
3. Call `mount_funnel` once for each desired path.
4. Call `connect_site_domain` with `confirm: true`.
5. Add only the exact records returned by Gringo at the DNS provider, then call
   `refresh_site_domain` until the hostname is active.

If the one-time TXT value is lost or expires before verification, call
`rotate_site_domain_claim` with `confirm: true`, replace only that TXT
record, and continue verification. Rotation is not available after the claim
has been verified.

The connection result can include a one-time `_gringo-claim` TXT record in
addition to the Cloudflare CNAME/TXT validation records. Do not reuse, guess,
or share the claim value. It prevents a dangling-CNAME takeover if a hostname
is removed and later claimed by another workspace.

### Permissions and billing

Sites use the existing v1 OAuth scopes to avoid breaking credentials already
issued to agents: `funnels:read` reads Sites, mounts, and domains;
`funnels:write` creates or changes Sites and mounts; `domains:write`
creates, verifies, or removes Site hostnames. Use least privilege—an agent that
only publishes should not receive `domains:write`.

Creating, rotating, or refreshing a custom hostname requires the workspace's
`custom_domains` entitlement to be active. Removing a mapping remains
available after cancellation so DNS is never held hostage. If an entitlement-required operation is missing access, the API returns
HTTP 402 and MCP returns:

`{ "error": "…", "code": "subscription_required", "status": 402 }`.

Agents must present that result to the account owner and leave DNS unchanged;
they must not retry, downgrade to another workspace, or attempt a registrar
login to bypass the subscription requirement.

## Discovery

- Human guide: https://gringofunnels.com/mcp
- Agent guide: https://gringofunnels.com/mcp/install.md
- Registry descriptor: https://gringofunnels.com/mcp/server.json
- Protected resource metadata: https://gringofunnels.com/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://gringofunnels.com/.well-known/oauth-authorization-server
- Machine-readable site index: https://gringofunnels.com/llms.txt