Quick Start Guide

This guide will help you set up your first SuperModel gateway server and generate a simple calculator UI app using MCP sampling and AG-UI.

Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed
MCP client that supports sampling (like Claude desktop)
Basic understanding of MCP and MCP-UI

Step 1: Install Dependencies

First, install the SuperModel framework and its dependencies:

npm

npm install @supermodel/gateway @supermodel/ag-ui-adapter
npm install @mcp-ui/server @mcp-ui/client

yarn

yarn add @supermodel/gateway @supermodel/ag-ui-adapter
yarn add @mcp-ui/server @mcp-ui/client

pnpm

pnpm add @supermodel/gateway @supermodel/ag-ui-adapter
pnpm add @mcp-ui/server @mcp-ui/client

Step 2: Create Gateway Configuration

Create a supermodel.config.json file to define your available UI tools:

supermodel.config.json

{
  "tools": {
    "calculator-ui": {
      "description": "Interactive calculator with basic arithmetic operations",
      "capabilities": ["arithmetic", "calculator", "math"]
    },
    "form-builder-ui": {
      "description": "Dynamic form generation and validation",
      "capabilities": ["forms", "validation", "input"]
    }
  },
  "adapters": {
    "ag-ui": {
      "enabled": true,
      "mimeType": "application/vnd.mcp-ui.ag-ui"
    }
  }
}

Step 3: Implement Gateway Server

Create your main server file:

server.ts

import { SuperModelGateway } from '@supermodel/gateway';
import { AGUIAdapter } from '@supermodel/ag-ui-adapter';
import { createUIResource } from '@mcp-ui/server';

const gateway = new SuperModelGateway({
  configPath: './supermodel.config.json',
  adapters: {
    'ag-ui': new AGUIAdapter()
  }
});

// Register calculator tool
gateway.registerTool('calculator-ui', async (request, context) => {
  // Use MCP sampling to generate calculator UI
  const samplingResponse = await gateway.sample({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Create an AG-UI calculator component with buttons 0-9, +, -, *, /, =, clear. 
               Use AG-UI event system for interactions. Request context: ${JSON.stringify(context)}`
      }
    }],
    systemPrompt: "Generate complete AG-UI React component. Include event handlers for AG-UI protocol.",
    maxTokens: 1500
  });

  // Package as MCP-UI resource
  return createUIResource({
    uri: `ui://calculator/calc-${Date.now()}`,
    content: {
      type: 'agui',
      component: samplingResponse.content.text
    },
    delivery: 'text'
  });
});

// Start the server
gateway.listen(3000, () => {
  console.log('SuperModel gateway running on port 3000');
});

Step 4: Test Your First UI Generation

Now test your setup with a simple request. In your MCP client, connect to your server and try:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_ui",
    "arguments": {
      "request": "Show me a calculator"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Here's your calculator:"
      },
      {
        "type": "resource",
        "resource": {
          "uri": "ui://calculator/calc-1704067200000",
          "mimeType": "application/vnd.mcp-ui.ag-ui",
          "text": "function Calculator() { /* AG-UI component */ }"
        }
      }
    ]
  }
}

What Happens Behind the Scenes

Here’s the zero-inference flow that just occurred:

Request Routing

Gateway uses MCP sampling to ask your client’s LLM: “Which tool should handle ‘Show me a calculator’?”

Tool Selection

Your LLM responds: {"tool": "calculator-ui", "params": {"type": "basic"}}

UI Generation

Calculator tool uses MCP sampling to generate AG-UI component code

Resource Packaging

Generated code is wrapped as an MCP-UI resource and returned

Zero Server Costs: Notice that your server made no LLM API calls. All reasoning happened on the client side through MCP sampling!

Next Steps

Multi-App Workflows

Build complex user journeys that span multiple specialized UI apps.

Gateway Pattern

Deep dive into intelligent routing and tool orchestration.

Context Handoff

Enable seamless transitions between apps with context preservation.

Troubleshooting

MCP Sampling Not Working

Ensure your MCP client supports sampling and that you’ve properly configured the sampling capability in your client setup.

UI Not Rendering

Check that your client supports the application/vnd.mcp-ui.ag-ui MIME type. You may need to extend MCP-UI with the AG-UI bridge.

Routing Failures

Verify your tool configurations and ensure the routing prompts are clear about available tools and their capabilities.

Getting Started

Core Concepts

Examples

Quick Start

Quick Start Guide

Prerequisites

Step 1: Install Dependencies

Step 2: Create Gateway Configuration

Step 3: Implement Gateway Server

Step 4: Test Your First UI Generation

What Happens Behind the Scenes

Next Steps

Multi-App Workflows

Gateway Pattern

Context Handoff

Troubleshooting

​Quick Start Guide

​Prerequisites

​Step 1: Install Dependencies

​Step 2: Create Gateway Configuration

​Step 3: Implement Gateway Server

​Step 4: Test Your First UI Generation

​What Happens Behind the Scenes

​Next Steps

Multi-App Workflows

Gateway Pattern

Context Handoff

​Troubleshooting

Quick Start Guide

Prerequisites

Step 1: Install Dependencies

Step 2: Create Gateway Configuration

Step 3: Implement Gateway Server

Step 4: Test Your First UI Generation

What Happens Behind the Scenes

Next Steps

Troubleshooting