> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermodel.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with SuperModel in under 10 minutes

# 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](https://modelcontextprotocol.org) and [AG-UI](https://ag-ui.com).

## Prerequisites

Before you begin, make sure you have:

* **Node.js 18+** installed
* **MCP client** that supports sampling (like Claude desktop)
* **Basic understanding** of [MCP](https://modelcontextprotocol.org) and [MCP-UI](https://mcp-ui.dev)

## Step 1: Install Dependencies

First, install the SuperModel framework and its dependencies:

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

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

```bash 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:

```json 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:

```typescript 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:

<CodeGroup>
  ```json MCP Request
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_ui",
      "arguments": {
        "request": "Show me a calculator"
      }
    }
  }
  ```

  ```json Expected Response
  {
    "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 */ }"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

## What Happens Behind the Scenes

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

<Steps>
  <Step title="Request Routing">
    Gateway uses MCP sampling to ask your client's LLM: "Which tool should handle 'Show me a calculator'?"
  </Step>

  <Step title="Tool Selection">
    Your LLM responds: `{"tool": "calculator-ui", "params": {"type": "basic"}}`
  </Step>

  <Step title="UI Generation">
    Calculator tool uses MCP sampling to generate AG-UI component code
  </Step>

  <Step title="Resource Packaging">
    Generated code is wrapped as an MCP-UI resource and returned
  </Step>
</Steps>

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-App Workflows" icon="workflow" href="/examples/multi-app-workflow">
    Build complex user journeys that span multiple specialized UI apps.
  </Card>

  <Card title="Gateway Pattern" icon="route" href="/concepts/gateway-pattern">
    Deep dive into intelligent routing and tool orchestration.
  </Card>

  <Card title="Context Handoff" icon="arrow-right-arrow-left" href="/examples/context-handoff">
    Enable seamless transitions between apps with context preservation.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP Sampling Not Working">
    Ensure your MCP client supports sampling and that you've properly configured the sampling capability in your client setup.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Routing Failures">
    Verify your tool configurations and ensure the routing prompts are clear about available tools and their capabilities.
  </Accordion>
</AccordionGroup>