Add Signals MCP tutorial: manage Signals with AI assistants

[jborlase-snowplow]

What changed?

New tutorial tutorials/signals-mcp/ (5 pages + 3 live Console screenshots): connect the Snowplow MCP server to an AI assistant (Claude Code in the examples), define/test/publish a Signals attribute group conversationally, verify results in Console and via the Python SDK, then make a conversational edit and republish.

Why?

No tutorial covered managing Signals through the MCP server, despite it being the primary agentic workflow (tutorials gap analysis).

Reviewer guidance

• The conversational flow is real: every transcript is condensed from actual MCP tool calls against a trial org, with attribute values asserted end-to-end (create → publish → events → exact-value retrieval → edit → republish). Console wording and screenshots verified/captured live.
• Trial orgs have no warehouse destination, so test_attribute_group 400s and Console hides Run preview entirely — the tutorial documents this as the expected trial path. The quickstart documents the button unconditionally; separate docs fix suggested.
• Found during verification, flagged for separate follow-up: MCP update edits a published group in place (docs say new version); the connection docs' Bearer curl example 405s (registry endpoints need a trailing slash).
• Open question: pages name the group tut_mcp_session_metrics so transcripts match the real run exactly — happy to rename at review.

🤖 Generated with Claude Code

[claude]

Style and writing review

Read CLAUDE.md, src/pages/style-guide/llm/index.md, and tutorial-requirements/README.md against the diff. This is a well-written tutorial — no marketing language, no smart quotes, no exclamations, Oxford commas throughout, correct "log in"/"set up" verb forms, correct "entity" (not "context") terminology, and Profiles Store plus the **Signals** > **Overview** breadcrumb styling consistent with the rest of /docs/signals/. All three images have descriptive alt text and live in an images/ subdirectory.

Links: all internal paths and anchors verified to exist (#create-an-api-key, #backfill-attributes, #configuration-workflow, #versioning, #test-the-attribute-definitions, and the three sibling tutorial entry pages). External URLs touched by this PR: github.com/snowplow/skills 200, claude.com/product/claude-code 200, snowplow.io/get-started/snowplow-free-trial 200. npmjs.com/package/mcp-remote returns 403 to automated fetches (bot protection), but the package resolves 200 on the npm registry, so the link is fine. console.snowplowanalytics.com links skipped as auth-gated.

A few things to fix:

---

1. "three values" introduces a two-item list

tutorials/signals-mcp/connect-the-mcp-server.md

You'll need three values:

1. Your organization ID, from the Manage organization page in Console settings
2. An API key ID and API key, which you create in Console

The count doesn't match the list, which makes the reader stop and recount. Style guide, Lists: items should be parallel, and the introducing sentence should match. Split item 2 so the list has three entries:

You'll need three values:

1. Your organization ID, from the **Manage organization** page in Console settings
2. An API key ID, which you [create in Console](/docs/account-management/#create-an-api-key)
3. The API key itself, shown once when you create it

2. Code span ending in a period, immediately followed by a comma

tutorials/signals-mcp/define-attributes-conversationally.md, in the :::note[Testing requires a warehouse connection] admonition:

the test fails with an error like This functionality is not available because there is no destination connection set up., and Console doesn't offer its Run preview option at all

The ., sequence reads as a typo. Drop the sentence-final period from inside the backticks and keep the comma outside:

the test fails with an error like This functionality is not available because there is no destination connection set up, and Console doesn't offer its Run preview option at all

3. Closing paragraph sits under the wrong heading

tutorials/signals-mcp/introduction.md

The final paragraph — "If you'd rather not set up an MCP client at all, the [Snowplow Assistant]…" — is the last thing on the page, so it falls under ## Prerequisites even though it isn't a prerequisite. Style guide, Page structure: content should sit under a heading it belongs to. Move it up so it closes the intro prose, directly before ## Prerequisites (a good spot is right after "This tutorial should take around 20 minutes to complete.").

4. Frontmatter titles aren't descriptive or unique

tutorials/signals-mcp/introduction.md and conclusion.md

title: "Introduction"

title: "Conclusion"

CLAUDE.md, Required frontmatter: title should be a "Descriptive title in sentence case, ideally unique across the site" — that's what renders as the page title and feeds SEO, while sidebar_label already handles the short navigation label. The sibling Signals tutorials do this, e.g. signals-quickstart/conclusion.md uses title: "Conclusions and next steps from the Signals quick start tutorial" with sidebar_label: "Conclusion". Suggest something like:

• title: "Manage Snowplow Signals conversationally with the MCP server" (introduction)
• title: "Conclusions and next steps from the Signals MCP tutorial" (conclusion)

The sidebar_label values stay as they are.

5. Minor: "No-setup alternative" heading

tutorials/signals-mcp/conclusion.md

No-setup alternative

Two small things: the style guide says to prefer "configuration" over "setup", and CLAUDE.md prefers imperative headings over noun phrases. ## Use the Snowplow Assistant instead covers both. (Noun-phrase headings appear elsewhere in the diff — ## Beyond attribute groups, ### How the credentials work, ### Other MCP clients — and those read fine in context, so no need to churn them; ## Next steps matches the sibling tutorials and should stay.)

6. Minor: bare URL as link text

tutorials/signals-mcp/connect-the-mcp-server.md

The plugin source lives at github.com/snowplow/skills

Style guide, Links: "Describe links clearly. Use the target page name where possible." Suggest: "The plugin source lives in the snowplow/skills repository".

7. Minor: filler "now"

tutorials/signals-mcp/define-attributes-conversationally.md

With the MCP server connected, you can now define your first attribute group by describing it.

The style guide bans "now" alongside "currently" and "latest". Here it's pure filler and can just be dropped: "With the MCP server connected, you can define your first attribute group by describing it." The other occurrences ("Signals is now calculating", "the group now calculates four attributes", "Now generate some data") are sequential rather than product-state, and read fine as-is.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	83a5766	Commit Preview URL Branch Preview URL	Aug 04 2026, 03:30 PM

[jborlase-snowplow]

Pushed f470c9de addressing product-owner feedback and all seven items from the style review:

Product-owner feedback

• Removed the "How the credentials work" section (kept one pointer to the connection docs)
• Reader verification now goes through the Snowplow Inspector — the Python venv/SDK retrieval flow is gone. Note for reviewers: the Inspector instructions are written faithfully from docs/testing/snowplow-inspector/signals-integration/ but were not exercised (no extension available in the verification environment) — one human walk-through of page 4 would close that gap
• Versioning corrected: the edit/republish narrative now teaches creating a new version alongside the published one, which was re-verified live (v2 published beside v1, both computing independently, exact-value assertions). While re-verifying we confirmed a product bug worth filing separately: the MCP signals_update_attribute_group tool still silently mutates a published version in place, contradicting the documented (and correct) lifecycle

Style review items — all seven applied: three-item credentials list, code-span punctuation, the stranded intro paragraph, descriptive frontmatter titles, "Use the Snowplow Assistant instead" heading, repository link text, and the filler "now". Anchor safety was grep-verified repo-wide (no inbound links to the removed/renamed sections).

🤖 Generated with Claude Code

[jborlase-snowplow]

Pushed fd836705 — editorial sweep per product direction: the warehouse-testing note no longer shows the raw API error; it now states the warehouse-connection requirement positively and points readers without one to the live verification on the next page.

🤖 Generated with Claude Code

[jborlase-snowplow]

Pushed b78f9ab2 — product-owner edits:

• Prerequisites simplified: a Snowplow account and pipeline (no Micro mention)
• New Install in any assistant route recommended first: npx plugins add snowplow/skills (verified against the snowplow/skills README — vendor-neutral open-plugin that installs the MCP server + skills into Claude Code, Cursor, or Codex; --target claude-code variant included)
• OAuth is now the primary authentication path; Console API keys moved to an optional subsection
• The "Review the draft" paragraph replaced with the accurate two-sentence version (the assistant can publish; drafts simply aren't computed until published)
• The "pattern that makes this work" line removed

🤖 Generated with Claude Code

[jborlase-snowplow]

Pushed 83a57666 — the tutorial now presents two first-class routes through the same conversational flow: the Snowplow Assistant in Console (open it and go, with the admin-enablement fallback noted) or any MCP-connected assistant. The intro frames both; page 2 leads with the Assistant route ahead of the unchanged MCP setup; pages 3–4 are client-neutral (the prompts are identical); the conclusion's separate Assistant section is folded into the flow.

Honesty note for reviewers: the Assistant route is written from docs/llms-support/console-agent/ — the verification environment's Console session had expired, so the Assistant UI was not exercised and no parity claims are made beyond the docs (transcripts remain attributed to the MCP-route captures). One human walk of pages 2–4 through the Assistant panel would close that gap. Also flagged: meta.json's title/technologies now under-describe the two-route tutorial — left as specified pending an owner call.

🤖 Generated with Claude Code

[Matus Tomlein (matus-tomlein)]

LGTM!

[Matus Tomlein (matus-tomlein)]

Wouldn't a screenshot be useful here? It would help someone like me at least to visualize what we are talking about when skimming the text faster. I see we don't add screenshots for Snowplow Assistant in Console also in other parts of the docs, not sure if that is a conscious decision.

[Matus Tomlein (matus-tomlein)]

I didn't get a small table on the Snowplow Assistant, in that case it just summarized the data:

The test results for tut_mcp_session_metrics over a 1-day window are as follows:

first_referrer: Successfully captured values like "snowplow.io" and "www.google.com", along with some nulls where no referrer host was found.
most_recent_browser: Correct extracted browser names from the yauaa_context, including "Chrome" and "HeadlessChrome".
page_view_count: Returned nulls in the test output. This is expected behavior for the warehouse test tool, as it cannot accurately simulate rolling time-window aggregations (like PT15M) against static warehouse data. This attribute will function correctly once published to the streaming engine.
Everything looks correct for the attributes that can be validated in the warehouse. Would you like to go ahead and publish this attribute group?

[Matus Tomlein (matus-tomlein)]

I would also find a screenshot useful here too, just to visualize what we are doing here more quickly.

[Matus Tomlein (matus-tomlein)]

Version 2's page_view_count starts from zero for each session, because a stream group only counts events that arrive after it's published

It shouldn't – if the definition of the page_view_count attribute hasn't changed from v1, then the same computation and storage is shared between v1 and v2, so v2 should see the same data as v1 except for the new most_recent_page_title attribute.