home / mcp / agentic mcp demo server

Agentic MCP Demo Server

a small (MCP) server that showcases agentic commerce UX using MCP UI inside Goose

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aharvard-mcp_agentic-commerce": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000",
        "MCP_GEOCODE_USERAGENT": "mcp-agentic-commerce/1.0 (+https://squareup.com)"
      }
    }
  }
}

You run a lightweight MCP server that delivers an interactive, click-first UI for a simple restaurant discovery and ordering flow. It demonstrates how MCP UI blocks can drive an agent-centric experience, including finding restaurants, viewing menus, placing a fake order, and displaying a playful receipt. All data and actions are synthetic for demonstration purposes and not tied to real services or payments.

How to use

You interact with the server through an MCP client. Start a chat and send natural-language prompts like “Find coffee around Austin” or “Order two lattes from Midtown Bean.” The MCP UI renders as HTML cards and components in the chat, and your actions (button clicks, quantity edits) dispatch tool calls back to the agent to update the UI in real time. Use the local UI previews at /dev to explore the flow locally before trying live interactions.

Typical user flow you can try in a client: search for nearby restaurants, open a restaurant’s details, view its menu, assemble an order, place the order, and review the generated receipt. Remember this is a demo: there are no real sellers, payments, or data. The UI is fully synthetic and meant to illustrate how MCP blocks render and respond.

How to install

Prerequisites: Node.js 20 or later and a package manager. The project uses pnpm to install dependencies and run scripts.

# 1) Install dependencies
pnpm install

# 2) Generate demo data (optional; prebuilt data is included)
# Regenerate synthetic restaurants (5MB+ file)
# You can control density:
#   GEN_MIN_PER_CATEGORY=3 GEN_MAX_PER_CATEGORY=5 pnpm run generate:data
pnpm run generate:data

# Regenerate generic menus by category
pnpm run generate:menus

# 3) Start the MCP server in development mode
# HTTP server is available at 127.0.0.1:8000/mcp
pnpm run dev
# or start the MCP server in an alternative dev mode
pnpm run dev:mcp

Other important notes

Server endpoints expose a streamable HTTP MCP interface. The server renders a local UI preview at http://127.0.0.1:8000/dev and a sample route like http://127.0.0.1:8000/dev/restaurants?city=Austin&state=TX&query=bbq for quick checks.

Environment variables you may set to customize the local run include MCP_HOST, MCP_PORT, and MCP_GEOCODE_USERAGENT. The defaults are 127.0.0.1, 8000, and a useragent string that identifies the demo. These values can be overridden when starting the server or via your MCP client configuration.

Security and caveats

This is a demonstration only. Do not treat any generated content as factual or as coming from real services. No money movement occurs, and the order flow is a simulated experience for UX prototyping.

Deployment notes

For local testing, run the development commands provided and verify the UI renders correctly in your browser. If you intend to consume this MCP server from Goose or another MCP client, configure the client to point at http://127.0.0.1:8000/mcp as the MCP endpoint.

Example interaction paths

Find restaurants around a city, view a restaurant card, open its menu, add items to an order, place the order, and view a playful receipt. Each user action in the UI triggers a corresponding tool call to update the displayed UI components.

Available tools

find_restaurants

Search nearby synthetic restaurants by city/state and optional query, returning a UI list with buttons to view details or start an order.

view_restaurant

Show a details card for a selected restaurant, including address, hours, phone, website, and CTA actions.

view_menu

Display a menu for a given restaurant. If a mock Square is detected, use a mock catalog; otherwise render a generic menu by primary category.

order_takeout

Present an interactive order table where you can edit quantities, remove items, and see totals before placing the order.

view_receipt

Render a playful, fake receipt for the completed order flow.