docs(build-mcp-server, quickstart): swap Reddit demo for GitHub star

[thierrypdamiba]

Important

Depends on ArcadeAI/arcade-mcp#850 — do not merge before #850 lands.

This PR updates the public docs to describe a tool that doesn't exist in the scaffold until #850 ships. Merging in the wrong order would leave the guides describing a tool tutorial readers can't generate. Opened as draft to make the ordering enforceable; will flip to ready-for-review the moment #850 merges.

Summary

Updates the build-mcp-server guide and the MCP server quickstart so they describe the new GitHub star_repo demo from the minimal scaffold instead of the broken Reddit get_posts_in_subreddit demo.

Today, a tutorial reader runs through either page, hits the consent URL Arcade prints, and Reddit's authorize endpoint returns:

bad request (reddit.com) — you sent an invalid request — invalid client id

…which is unfixable in this repo (or on the Arcade Engine side without Reddit's manual re-approval under their November 2025 Responsible Builder Policy). Issue #976 (filed by @naganowl) captures the bug in detail.

The scaffold fix lands in ArcadeAI/arcade-mcp#850. This PR is its paired docs update so the guides match the scaffold the moment that lands.

Resolves: #976 (docs side; the auth-provider reference page rewrite is separate)

Design decisions

• Why only the build-mcp-server guide and the MCP quickstart. Those are the two pages that walk a reader through arcade new <name> → run server → invoke the auth-required tool. Other docs that mention Reddit (the auth-provider reference, blog posts, the arcade-tdk README) describe Reddit-the-provider as a concept, not the scaffold demo, so they don't break under [AUTO] Adding MCP Servers docs update #850 and aren't in scope here.
• Why mirror [AUTO] Adding MCP Servers docs update #850's prose almost verbatim. The scaffold's prior demo and the guides were tightly coupled (line counts, tool names, expected log output). Keeping the docs prose close to the scaffold's prose minimizes drift between the two sources of truth.
• Why update the example prompt from "Get some posts from the r/mcp subreddit" to "Star the ArcadeAI/arcade-mcp repository on GitHub". Same idea: the example prompt the reader copies has to match the tool they actually have. Picking ArcadeAI/arcade-mcp as the target repo is on-brand and gives the reader a satisfying visible side effect (their star lands on the repo they're learning to use).
• Why update the "Reddit tool is not working" troubleshooting heading to "The GitHub tool is not working". Same surface-area-as-scaffold consistency.
• Why update the example log output from Added tool: get_posts_in_subreddit to Added tool: star_repo. The reader copy-pastes the run command and checks their terminal against this exact line; if it doesn't match, the guide loses credibility.
• Corrected the User-Agent string in the code snippet from finally-mcp-server to my_server-mcp-server so it matches what arcade new my_server actually renders (the scaffold uses {{ toolkit_name }}-mcp-server, which expands to my_server-mcp-server for the guide's example name). Pre-existing drift, caught while updating the snippet.

Scope

In scope:

• app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx — the main tutorial
• app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx — the quickstart that mirrors the same flow

Not in scope (separate decisions):

• app/en/references/auth-providers/reddit/page.mdx — the Reddit auth-provider reference page itself. The provider entry can stay (it describes how to integrate Reddit auth if/when Reddit re-approves Arcade); only the tutorial needed pivoting.
• Other Reddit mentions across blog posts, the arcade-tdk README in the arcade-mcp repo, or example MCP servers under examples/mcp_servers/authorization/. Those describe Reddit-as-a-provider conceptually, not as the scaffolded demo, and don't break under [AUTO] Adding MCP Servers docs update #850.
• The auth-provider reference page rewrite tracked separately in Update Reddit auth provider docs #976.

Test plan

• pnpm run lint (or repo equivalent) on the two changed .mdx files — clean
• Spot-rendered both pages locally and visually confirmed:
  • Code block highlighting still works after the swap (Python in both)
  • The example consent flow text reads sensibly with GitHub substituted in for Reddit
  • No dangling references to "subreddit", "post", or get_posts_in_subreddit remain in either file
• All hyperlinks in the diff are still resolvable (the GitHub developer settings URL the page used to point at for Reddit is replaced with prose since GitHub's OAuth setup isn't a step the reader takes here)
• Cross-checked that the User-Agent string, the tool name (star_repo), and the example invocation match the rendered output of arcade new my_server from fix(arcade-cli): swap minimal scaffold demo from Reddit to GitHub star arcade-mcp#850's branch — verified by running arcade new my_server against that branch and diffing
• Merge order: [AUTO] Adding MCP Servers docs update #850 merges first → flip this PR to ready-for-review → land

Risk note

Pure docs change. Zero runtime impact. The only real risk is merge-order — if this lands before #850, the guides describe a tool that the scaffold doesn't produce yet, which would actively confuse the next tutorial reader. The draft state on this PR is the merge-order guardrail.

Author checklist

• Linked to a Linear ticket or GitHub issue (docs#976, above)
• I understand every change in the diff — every prose/code change in the diff has a 1:1 counterpart in the scaffold PR
• Visually rendered the affected pages
• CI is expected to pass (docs-only)
• I've pulled the branch fresh and reviewed my own diff top-to-bottom
• Draft state explicitly used to prevent out-of-order merge

---

Note

Low Risk
Low risk docs-only change; main risk is guidance mismatch if merged before the corresponding scaffold change that generates star_repo.

Overview
Swaps the scaffolded auth-demo in docs from Reddit to GitHub. The quickstart and build-mcp-server guide now describe and show a star_repo tool (GitHub OAuth) instead of get_posts_in_subreddit (Reddit).

Updates the embedded server.py snippet and surrounding instructions accordingly (GitHub auth provider, PUT /user/starred/{owner}/{repo} call, updated headers/User-Agent), and adjusts expected log output, example prompt, and troubleshooting copy to reference the GitHub tool.

^{Reviewed by Cursor Bugbot for commit 783cd1b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 23, 2026 4:25am

[Copilot]

Pull request overview

Updates the MCP server tutorial docs to match the updated arcade new minimal scaffold by replacing the broken Reddit authorization demo tool with a GitHub “star repo” demo, so readers can successfully complete the auth-required tool flow.

Changes:

• Replaced the Reddit get_posts_in_subreddit example tool with a GitHub star_repo tool in the build guide’s server.py snippet (including headers and expected output).
• Updated the MCP server quickstart to describe/invoke star_repo and adjusted troubleshooting text and sample logs accordingly.
• Aligned the example User-Agent string with the arcade new my_server scaffold output.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx	Swaps the tutorial’s auth-required tool from Reddit to GitHub and updates the example code/log output to star_repo.
app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx	Updates the quickstart narrative, prompts, logs, and troubleshooting to use the GitHub star_repo demo.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.