Build with Gami

Overview

Gami Protocol ships four cooperative AI agents that orchestrate player engagement across any Web2 or Web3 application. Each agent exposes a Model-Context-Protocol (MCP) endpoint so external tools, dashboards, and other agents can query its state or push directives at runtime.

Connecting to the MCP Server

The MCP server is the backbone of all agent telemetry. It streams Server-Sent Events (SSE) over a single persistent connection and accepts broadcast commands via a REST endpoint.

# .env.local — set these in Vercel
MCP_SERVER_URL=https://your-mcp-host.example.com
NEXT_PUBLIC_AGENT_STREAM_URL=https://your-mcp-host.example.com/api/stream

# Check server health
curl https://your-mcp-host.example.com/health

# SSE stream (browser — no auth for demo)
curl -N https://your-mcp-host.example.com/api/stream

Agent-to-Agent Communication

Agents communicate via the broadcast endpoint. Any agent (or supervisor) can post a JSON envelope to /api/mcp/broadcast and every subscribed agent will receive it over the SSE stream.

// Broadcast from your app
await fetch("/api/mcp/broadcast", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    source: "supervisor",       // who is sending
    target: "quest",            // optional — omit to fan-out to all agents
    type:   "directive",
    payload: {
      action:    "pause_quest",
      quest_id:  "q-abc123",
      reason:    "fraud_flag",
    },
    timestamp: Date.now(),
  }),
});

Building with Gami Agent (Python)

The gami-agent Python package lets you register custom agents that join the same MCP mesh. Install from PyPI then point it at your MCP server URL.

# Install
pip install gami-agent

# quickstart.py
from gami_agent import Agent, MCPClient

client = MCPClient(url="https://your-mcp-host.example.com")

@Agent(name="custom-loyalty", client=client)
async def handle_quest_completed(event):
    """Called every time quest.completed fires."""
    wallet  = event.payload["wallet_id"]
    xp      = event.payload["xp_awarded"]
    # … apply custom loyalty logic …
    await client.broadcast({
        "source":  "custom-loyalty",
        "type":    "loyalty.bonus_applied",
        "payload": {"wallet_id": wallet, "bonus_xp": xp * 0.1},
    })

Vercel Deployment (Recommended)

Deploy the Next.js app directly to Vercel. This keeps App Router pages and API routes running with minimal configuration while preserving MCP proxy routes under /api/mcp/* for agent streaming and broadcast.

# Install dependencies
npm install

# Local production check
npm run build

# Deploy (CLI)
npm i -g vercel
vercel

# Set environment variables in Vercel Project Settings:
# NEXT_PUBLIC_FIREBASE_*
# MCP_SERVER_URL
# NEXT_PUBLIC_AGENT_STREAM_URL
# DATABASE_URL
# RESEND_API_KEY

Cloudflare Connect Points

If your MCP backend is on Cloudflare (Workers/Pages), keep the web app on Vercel and point both MCP variables to the Cloudflare host. The built-in API proxy routes avoid browser CORS issues and keep agent telemetry stable.

# Example
MCP_SERVER_URL=https://gami-mcp.yourdomain.workers.dev
NEXT_PUBLIC_AGENT_STREAM_URL=https://gami-mcp.yourdomain.workers.dev/api/stream

# App routes used by the dashboard:
# GET  /api/mcp/health
# GET  /api/mcp/stream
# POST /api/mcp/broadcast

Firebase Authentication

Login and Sign-Up are powered by Firebase Auth. Email/password, Google OAuth and GitHub OAuth are all wired up. Set the following environment variables (use NEXT_PUBLIC_ prefix for client-side vars):

# .env.local
NEXT_PUBLIC_FIREBASE_API_KEY=AIza...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abc

# In Firebase Console:
#  Authentication → Sign-in method → enable Email/Password, Google, GitHub
#  Authorised domains → add your Vercel domain

API Reference

Quick reference for the built-in Next.js API routes.

{ "source": string, "message": string, "target"?: string, "timestamp": number }

{ "email": string }