MCP Starter for Puch AI

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 authentication. Keep it safe!
MY_NUMBER: Your WhatsApp number in format {country_code}{number} (e.g., 919876543210 for +91-9876543210)

Step 3: Run the Server

cd mcp-bearer-token
python mcp_starter.py

You'll see: 🚀 Starting MCP server on http://0.0.0.0:8086

Step 4: Make It Public (Required by Puch)

Since Puch needs to access your server over HTTPS, you need to expose your local server:

Option A: Using ngrok (Recommended)

Install ngrok: Download from https://ngrok.com/download
Get your authtoken:
- Go to https://dashboard.ngrok.com/get-started/your-authtoken
- Copy your authtoken
- Run: ngrok config add-authtoken YOUR_AUTHTOKEN
Start the tunnel:
```
ngrok http 8086
```

Option B: Deploy to Cloud

You can also deploy this to services like:

Railway
Render
Heroku
DigitalOcean App Platform

How to Connect with Puch AI

Open Puch AI in your browser
Start a new conversation

Use the connect command:

/mcp connect https://your-domain.ngrok.app/mcp your_secret_token_here

Debug Mode

To get more detailed error messages:

/mcp diagnostics-level debug

Customizing the Starter

Adding New Tools

Create a new tool function:

@mcp.tool(description="Your tool description")
async def your_tool_name(
    parameter: Annotated[str, Field(description="Parameter description")]
) -> str:
    # Your tool logic here
    return "Tool result"

Add required imports if needed

📚 Additional Documentation Resources

Official Puch AI MCP Documentation

Main Documentation: https://puch.ai/mcp
Protocol Compatibility: Core MCP specification with Bearer & OAuth support
Command Reference: Complete MCP command documentation
Server Requirements: Tool registration, validation, HTTPS requirements

Technical Specifications

JSON-RPC 2.0 Specification: https://www.jsonrpc.org/specification (for error handling)
MCP Protocol: Core protocol messages, tool definitions, authentication

Supported vs Unsupported Features

✓ Supported:

Core protocol messages
Tool definitions and calls
Authentication (Bearer & OAuth)
Error handling

✗ Not Supported:

Videos extension
Resources extension
Prompts extension

Getting Help

Join Puch AI Discord: https://discord.gg/VMCnMvYx
Check Puch AI MCP docs: https://puch.ai/mcp
Puch WhatsApp Number: +91 99988 81729

Happy coding! 🚀

Use the hashtag #BuildWithPuch in your posts about your MCP!

This starter makes it super easy to create your own MCP server for Puch AI. Just follow the setup steps and you'll be ready to extend Puch with your custom tools!