Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thierrypdamiba wants to merge 2 commits into
base: main
Choose a base branch
from
+21 −26
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca93689
docs(build-mcp-server, quickstart): swap Reddit demo for GitHub star
thierrypdamiba May 21, 2026
783cd1b
Update docs to match merged implementation
thierrypdamiba May 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ my_server/

- **`greet`**: This tool has a single argument, the name of the person to greet. It requires no secrets or auth
- **`whisper_secret`**: This tool requires no arguments, and will output the last 4 characters of a `MY_SECRET_KEY` secret that you can define in your `.env` file.
- **`get_posts_in_subreddit`**: This tool has a single argument, a subreddit, and will return the latest posts on that subreddit, it requires the user to authorize the tool to perform a read operation on their behalf.
- **`star_repo`**: This tool takes a GitHub `owner` and `repo` name and stars that public repository on behalf of the authenticated user. It requires the user to authorize the tool to act on their behalf.

> If you're having issues with the `arcade` command, please see the [Troubleshooting](#troubleshooting) section.

Expand Down Expand Up @@ -158,7 +158,7 @@ $env:MY_SECRET_KEY="my-secret-value"

## Connect to Arcade to unlock authorized tool calling

Since the Reddit tool accesses information only available to your Reddit account, you'll need to authorize it. For this, you'll need to create an <SignupLink linkLocation="docs:mcp-server-quickstart" utmCampaign="docs-quickstart-mcp-server">Arcade account</SignupLink> and connect from the terminal, run:
Since the GitHub tool stars a repository on your behalf, you'll need to authorize it. For this, you'll need to create an <SignupLink linkLocation="docs:mcp-server-quickstart" utmCampaign="docs-quickstart-mcp-server">Arcade account</SignupLink> and connect from the terminal, run:

```bash
arcade login
Expand Down Expand Up @@ -219,7 +219,7 @@ You should see output like this in your terminal:
```bash
2025-11-03 13:46:11.041 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: greet
2025-11-03 13:46:11.042 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: whisper_secret
2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: get_posts_in_subreddit
2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: star_repo
INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools
```

Expand Down Expand Up @@ -272,7 +272,7 @@ Try calling your tool inside your assistant.

Here's some prompts you can try:

- "Get some posts from the r/mcp subreddit"
- "Star the ArcadeAI/arcade-mcp repository on GitHub"
- "What's the last 4 characters of my secret key?"
- "Greet me as Supreme Lord of MCP"

Expand All @@ -284,7 +284,7 @@ Here's some prompts you can try:

If you're getting issues with the `arcade` command, please make sure you did not install it outside of your virtual environment. For example, if your system-wide Python installation older than 3.10, you may need to uninstall arcade from that Python installation in order for the terminal to recognize the `arcade` command installed in your virtual environment.

### The Reddit tool is not working
### The GitHub tool is not working

Ensure you run `arcade login` and follow the instructions in your browser to connect your terminal to your Arcade account.

Expand Down
37 changes: 16 additions & 21 deletions app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,17 +97,15 @@ from typing import Annotated

import httpx
from arcade_mcp_server import Context, MCPApp
from arcade_mcp_server.auth import Reddit
from arcade_mcp_server.auth import GitHub

app = MCPApp(name="my_server", version="1.0.0", log_level="DEBUG")


@app.tool
def greet(name: Annotated[str, "The name of the person to greet"]) -> str:
"""Greet a person by name."""
return f"Hello, {name}!"


# To use this tool locally, you need to either set the secret in the .env file or as an environment variable
@app.tool(requires_secrets=["MY_SECRET_KEY"])
def whisper_secret(context: Context) -> Annotated[str, "The last 4 characters of the secret"]:
Expand All @@ -124,32 +122,29 @@ def whisper_secret(context: Context) -> Annotated[str, "The last 4 characters of

# To use this tool locally, you need to install the Arcade CLI (uv tool install arcade-mcp)
# and then run 'arcade login' to authenticate.
@app.tool(requires_auth=Reddit(scopes=["read"]))
async def get_posts_in_subreddit(
context: Context, subreddit: Annotated[str, "The name of the subreddit"]
) -> dict:
"""Get posts from a specific subreddit"""
# Normalize the subreddit name
subreddit = subreddit.lower().replace("r/", "").replace(" ", "")

# Prepare the httpx request
@app.tool(requires_auth=GitHub())
async def star_repo(
context: Context,
owner: Annotated[str, "GitHub owner (user or org). E.g. 'ArcadeAI'"],
repo: Annotated[str, "GitHub repository name. E.g. 'arcade-mcp'"],
) -> Annotated[str, "Confirmation that the repository was starred"]:
"""Star a public GitHub repository on behalf of the authenticated user."""
# OAuth token is injected into the context at runtime.
# LLMs and MCP clients cannot see or access your OAuth tokens.
oauth_token = context.get_auth_token_or_empty()
headers = {
"Authorization": f"Bearer {oauth_token}",
"User-Agent": "finally-mcp-server",
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": "2022-11-28",
"User-Agent": "my_server-mcp-server",
}
params = {"limit": 5}
url = f"https://oauth.reddit.com/r/{subreddit}/hot"
url = f"https://api.github.com/user/starred/{owner}/{repo}"

# Make the request
async with httpx.AsyncClient() as client:
response = await client.get(url, headers=headers, params=params)
response = await client.put(url, headers=headers)
response.raise_for_status()

# Return the response
return response.json()
return f"Starred {owner}/{repo}."

# Run with specific transport
if __name__ == "__main__":
Expand Down Expand Up @@ -225,7 +220,7 @@ $env:MY_SECRET_KEY="my-secret-value"

## Connect to Arcade to unlock authorized tool calling

Since the Reddit tool accesses information only available to your Reddit account, you'll need to authorize it. For this, you'll need to create an Arcade account and connect to it from the terminal, run:
Since the GitHub tool stars a repository on your behalf, you'll need to authorize it. For this, you'll need to create an Arcade account and connect to it from the terminal, run:

```bash
arcade login
Expand Down Expand Up @@ -285,7 +280,7 @@ You should see output like this in your terminal:
```bash
2025-11-03 13:46:11.041 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: greet
2025-11-03 13:46:11.042 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: whisper_secret
2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: get_posts_in_subreddit
2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: star_repo
INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools
```

Expand Down
Loading