Skip to main content

​
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"
    }
  }
}

​
What Happens Behind the Scenes

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

Request Routing

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

Tool Selection

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

UI Generation

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

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

Ensure your MCP client supports sampling and that you’ve properly configured the sampling capability in your client setup.
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.
Verify your tool configurations and ensure the routing prompts are clear about available tools and their capabilities.