Agentic Development Kit (ADK) - Python

A sample agentic e-commerce application that demonstrates how to build an MCP server that integrates with AI agents like ChatGPT. Users can browse products, manage a cart, and complete purchases through natural language conversation.

Learn more: Check out our full guide on building agentic applications for a step-by-step walkthrough. (Link coming soon)

What this demonstrates

• MCP Server built with FastMCP exposing tools and resources to AI agents
• OAuth authentication via Google, proxied through the MCP auth layer for ChatGPT integration
• Payment processing with Gr4vy including card management, Embed widget, and 2FA checkout flow
• Persistent storage with Google Cloud Firestore for user data and OAuth state
• UI widgets (HTML) served as MCP resources for rich in-chat rendering

How it works

This app uses ChatGPT's MCP integration to expose tools (actions the model can invoke) and resources (HTML widgets rendered inline in the chat).

1. ChatGPT calls an MCP tool (e.g. list_products) based on the user's message.
2. The tool returns structured data (structuredContent) plus metadata pointing to a widget resource URI via openai/outputTemplate.
3. ChatGPT fetches the widget — an HTML file registered as an MCP resource with MIME type text/html+skybridge.
4. The widget renders inline in the conversation, reading the tool's structured data to display an interactive UI.
5. The user interacts with the widget (browses products, adjusts cart, checks out). The widget communicates back to ChatGPT to trigger new tool calls.

Architecture

ChatGPT  <──MCP──>  MCP Server  <──>  Gr4vy (payments)
                         │
                         ├── Google OAuth (authentication)
                         └── Firestore (user data, OAuth state)

The server exposes MCP tools that the AI agent can call:

Tool	Description
list_products	Browse the product catalog, optionally filtered by category
show_cart	Display the shopping cart with selected items
start_checkout	Initialize checkout with Gr4vy Embed for payment
pay	Process a one-step payment with a stored card
list_cards	List the user's saved payment cards
checkout_tokenize	Step 1 of 2FA checkout: generate a payment token
checkout_verify	Step 2 of 2FA checkout: verify the 2FA code
checkout_purchase	Step 3 of 2FA checkout: complete the purchase

Prerequisites

• Python 3.10+
• A Google Cloud project with OAuth 2.0 credentials and Firestore enabled
• A Gr4vy account with API credentials

Setup

1. Clone the repository:

   git clone <repo-url>
   cd gr4vy-python-adk
   

2. Install dependencies:

   pip install .
   

3. Configure environment variables:

   cp .env.example .env
   

   Edit .env with your credentials:

   Variable	Description
   BASE_URL	Public URL where the server is deployed
   GOOGLE_CLIENT_ID	Google OAuth client ID
   GOOGLE_CLIENT_SECRET	Google OAuth client secret
   GOOGLE_APPLICATION_CREDENTIALS	Path to Firebase service account JSON (local dev only)
   GR4VY_ID	Gr4vy account ID
   GR4VY_PRIVATE_KEY	Gr4vy private key
   GR4VY_MERCHANT_ACCOUNT_ID	Gr4vy merchant account ID
   FIRESTORE_PROJECT	Google Cloud project ID for Firestore
   HOST	Server bind address (default: 0.0.0.0)
   PORT	Server port (default: 8000)

4. Set up Google OAuth:

   In the Google Cloud Console, configure your OAuth consent screen and add the authorized redirect URI:

   {BASE_URL}/auth/callback
   

Running

Local development:

python server.py

The server starts at http://localhost:8000.

With Docker:

docker build -t adk-python .
docker run -p 8000:8000 --env-file .env adk-python

Production (Google Cloud Run):

On Cloud Run, Firestore credentials are auto-configured via the service account -- no need to set GOOGLE_APPLICATION_CREDENTIALS.

Try it out

Start a conversation with the app enabled and try prompts like:

• "What plants do you have?"
• "Show me something low-maintenance"
• "Add the Monstera to my cart"
• "Show my cart"
• "I'd like to checkout"

Tech stack

• Server: Python 3.10+, FastMCP
• Payments: Gr4vy Embed + gr4vy SDK
• Auth: Google OAuth 2.0
• Database: Google Cloud Firestore
• Widgets: Self-contained HTML files served as MCP resources

Project structure

├── server.py              # MCP server, OAuth config, tool definitions
├── products.py            # Product catalog data
├── cards.py               # Card management
├── purchases.py           # Payment processing and checkout logic
├── firebase_client.py     # Firestore database client
├── assets/                # HTML widgets for in-chat UI
│   ├── product-catalog.html
│   ├── shopping-cart.html
│   └── checkout.html
├── pyproject.toml         # Python project config and dependencies
├── Dockerfile             # Container build
└── .env.example           # Environment variable template

License

This project is licensed under the MIT License.