StarterBLOCK
Starter code to add MCPs to Puch AI #BuildWithPuch
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
This is a starter template for creating your own Model Context Protocol (MCP) server that works with Puch AI. It comes with ready-to-use tools for job searching and image processing.
What is MCP?
MCP (Model Context Protocol) allows AI assistants like Puch to connect to external tools and data sources safely. Think of it like giving your AI extra superpowers without compromising security.
What's Included in This Starter?
Folders
- `mcp-bearer-token/`
Example MCP servers using Bearer token auth (required by Puch AI). Includes:
- `mcp_starter.py`
A minimal MCP server with:
- Text input/output tool (echo-style processing)
- Image input/output tool (e.g., convert to black & white)
- Bearer token validation
- `puch-user-id-mcp-example.py`
A task management MCP server that demonstrates how to use puch_user_id (a unique, Puch-provided user identifier) to scope tasks and data per user.
- `mcp-google-oauth/`
Example MCP server showing how to implement OAuth with Google for MCP authentication/authorization.
- `mcp-oauth-github/`
Example MCP server showing how to implement OAuth with GitHub for MCP authentication/authorization.
Quick Setup Guide
Step 1: Install Dependencies
First, make sure you have Python 3.11 or higher installed. Then:
# Create virtual environment uv venv # Install all required packages uv sync # Activate the environment source .venv/bin/activate
Step 2: Set Up Environment Variables
Create a .env file in the project root:
# Copy the example file cp .env.example .env
Then edit .env and add your details:
AUTH_TOKEN=your_secret_token_here MY_NUMBER=919876543210
Important Notes:
AUTH_TOKEN: This is your secret token for authe
75331f38b9e1OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add remote-mcp-github-oauth --env AUTH_TOKEN=${AUTH_TOKEN} -- npx -y [email protected]{
"mcpServers": {
"remote-mcp-github-oauth": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"AUTH_TOKEN": "${AUTH_TOKEN}"
}
}
}
}Exposed tools (5)
4 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
about | read | Description about this mcp server |
generateImage | read | Generate an image using the |
send_gmail | write | |
userInfoOctokit | read | Get user info from GitHub, via Octokit |
validate | read | Validated this mcp server to be used by PuchAI |
Trust audit
BLOCKgrade D · trust 67/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- declared (7 observation(s))
- Shell
- declared (2 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (16)
exec(input?: (string | URLPatternInit), baseURL?: string): URLPatternResult | null;
exec(query: string): Promise<D1ExecResult>;
.DS_Store
print("🚀 Starting MCP server on http://0.0.0.0:8086")print("🧭 Starting Task MCP server on http://0.0.0.0:8086 (in-memory store)").DS_Store
.dev.vars.example
.dev.vars.example
You'll see: `🚀 Starting MCP server on http://0.0.0.0:8086`
image_bytes = base64.b64decode(puch_image_data)
const oauthReqInfo = JSON.parse(atob(c.req.query('state') as string)) as AuthRequestconst jsonString = atob(encoded);
const payload = atob(base64Payload); // Assuming payload is base64 encoded JSON string
const oauthReqInfo = JSON.parse(atob(c.req.query("state") as string)) as AuthRequest;@cloudflare/workers-oauth-provider, agents, hono, just-pick, workers-mcp, zod, @cloudflare/workers-types, prettier
@cloudflare/workers-oauth-provider, agents, hono, just-pick, octokit, workers-mcp, zod, @cloudflare/workers-types
Gates applied: no_behavioural_pass.
75331f38b9e1full audit observations/trust-audit/mcp-server/turboml-inc__starter-1.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | 75331f38b9e1 | BLOCK | D | 67 | first audit |
Questions
What is the Starter MCP server?
Starter code to add MCPs to Puch AI #BuildWithPuch
What tools does Starter expose?
5 in total: 4 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is Starter safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (67/100) and found 2 critical or high issues in the source. Each one is listed on this page with the file and line it is on.
What credentials does Starter need?
It reads AUTH_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Starter run?
It speaks streamable-http, so it runs as a service you connect to over the network. It is published on npm as remote-mcp-github-oauth at 0.0.1.
How current is this page?
The grade is for one exact copy of the source (75331f38b9e1), read on 2026-10-07. The repository is watched and re-audited when it changes.