render-question-mcp

An MCP (Model Context Protocol) server that enables AI agents to collect structured, validated user input through native UI forms using elicitation.

Features

• 6 Question Types: text, number, boolean, radio, dropdown, checkbox (with true multi-select support!)
• Multi-Select Checkboxes: Native array support for selecting multiple options
• Comprehensive Validation: required fields, min/max values, patterns, email/URI formats
• Type-Safe: Built with TypeScript and Zod for runtime validation
• Native UI: Renders forms in the MCP client's native interface
• Zero Ambiguity: Eliminates conversational back-and-forth for data collection

Installation

Prerequisites

• Node.js >= 20.0.0
• An MCP-compatible client (Cursor, Claude Desktop, VS Code, etc.)

Getting Started

First, install the render-question-mcp server with your client.

Standard config works in most tools:

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": [
        "render-question-mcp@latest"
      ]
    }
  }
}

Use the Claude Code CLI to add the server:

claude mcp add render-question npx render-question-mcp@latest

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": ["render-question-mcp@latest"]
    }
  }
}

Click the button to install:

Or install manually:

Go to Cursor Settings → MCP → Add new MCP Server. Name to your liking, use command type with the command npx render-question-mcp@latest. You can also verify config or add command arguments via clicking Edit.

Project-Specific Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": ["render-question-mcp@latest"]
    }
  }
}

Follow the MCP install guide, use the standard config above.

Alternatively, install using the VS Code CLI:

code --add-mcp '{"name":"render-question","command":"npx","args":["render-question-mcp@latest"]}'

Add via the Cline VS Code extension settings or by updating your cline_mcp_settings.json file:

{
  "mcpServers": {
    "render-question": {
      "command": "npx",
      "args": [
        "render-question-mcp@latest"
      ]
    }
  }
}

Follow the MCP Servers documentation. Use the standard config above.

Local Development

For local development and testing:

{
  "mcpServers": {
    "render-question": {
      "command": "node",
      "args": ["/absolute/path/to/render-question-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Verify Installation

After installation, verify render-question-mcp is working:

1. Restart your MCP client completely
2. Check connection status:
   • Cursor: Look for green dot in Settings → Tools & Integrations → MCP Tools
   • Claude Desktop: Check for "render_question" in available tools
   • VS Code: Verify in GitHub Copilot settings
3. Test with a simple query:

   Ask me for my name and email address

If you see the AI agent use the render_question tool and display a native form, you're all set! 🎉

Usage

The server provides a single tool: render_question

Basic Example: Single Text Field

{
  "questions": [
    {
      "id": "email",
      "type": "text",
      "label": "What is your email address?",
      "validation": {
        "required": true,
        "format": "email"
      },
      "helpText": "We'll use this for project notifications",
      "placeholder": "[email protected]"
    }
  ]
}

Example: Multiple Questions Form

{
  "title": "Developer Onboarding",
  "description": "Help us set up your development environment",
  "questions": [
    {
      "id": "name",
      "type": "text",
      "label": "Your full name",
      "validation": {
        "required": true,
        "minLength": 2
      },
      "placeholder": "Jane Doe"
    },
    {
      "id": "experience",
      "type": "number",
      "label": "Years of experience with TypeScript",
      "validation": {
        "required": true,
        "min": 0,
        "max": 50
      }
    },
    {
      "id": "role",
      "type": "dropdown",
      "label": "What's your primary role?",
      "options": [
        { "value": "frontend", "label": "Frontend Developer" },
        { "value": "backend", "label": "Backend Developer" },
        { "value": "fullstack", "label": "Full-Stack Developer" },
        { "value": "devops", "label": "DevOps Engineer" }
      ],
      "validation": { "required": true }
    },
    {
      "id": "remote",
      "type": "boolean",
      "label": "Are you working remotely?",
      "default": true
    }
  ]
}

Question Types

Text Input

{
  "id": "username",
  "type": "text",
  "label": "Username",
  "validation": {
    "required": true,
    "minLength": 3,
    "maxLength": 20,
    "pattern": "^[a-zA-Z0-9_]+$"
  },
  "placeholder": "john_doe"
}

Number Input

{
  "id": "port",
  "type": "number",
  "label": "Port Number",
  "validation": {
    "required": true,
    "min": 1,
    "max": 65535
  },
  "default": 3000
}

Boolean (Single Checkbox)

{
  "id": "agree",
  "type": "boolean",
  "label": "I agree to the terms and conditions",
  "validation": {
    "required": true
  }
}

Radio Buttons (Single Choice)

{
  "id": "theme",
  "type": "radio",
  "label": "Select a theme",
  "options": [
    { "value": "light", "label": "Light Mode" },
    { "value": "dark", "label": "Dark Mode" },
    { "value": "auto", "label": "Auto (System)" }
  ],
  "validation": {
    "required": true
  }
}

Dropdown (Single Choice)

{
  "id": "framework",
  "type": "dropdown",
  "label": "Choose a framework",
  "options": [
    { "value": "react", "label": "React" },
    { "value": "vue", "label": "Vue.js" },
    { "value": "angular", "label": "Angular" },
    { "value": "svelte", "label": "Svelte" }
  ]
}

Checkbox (Multi-Select) ✨ NEW!

{
  "id": "features",
  "type": "checkbox",
  "label": "Select features to enable",
  "options": [
    { "value": "auth", "label": "Authentication" },
    { "value": "db", "label": "Database Integration" },
    { "value": "api", "label": "REST API" },
    { "value": "websocket", "label": "WebSocket Support" }
  ],
  "validation": {
    "min": 1,  // Require at least 1 selection
    "max": 3   // Allow maximum 3 selections
  },
  "helpText": "Choose all features you want to include"
}

Response format for multi-select:

{
  "features": ["auth", "db", "api"]  // Array of selected values
}

Validation Options

• required: boolean - Field must be filled
• min / max: number - Min/max value for numbers, or min/max items for checkbox arrays
• minLength / maxLength: number - Min/max length for strings
• pattern: string - Regular expression pattern
• format: "email" | "uri" | "url" | "date" | "date-time" - Format validation
• errorMessage: string - Custom error message

Response Format

The tool returns a structured response:

{
  "answers": {
    "name": "Jane Doe",
    "experience": 5,
    "role": "fullstack",
    "remote": true,
    "features": ["auth", "db", "api"]
  },
  "metadata": {
    "completedAt": "2025-11-13T10:30:00Z",
    "duration": 15000,
    "action": "submit"
  }
}

Possible actions:

• submit - User submitted the form
• cancel - User canceled the dialog
• decline - User declined to answer

Development

Setup

pnpm install
pnpm build

Testing

pnpm test
pnpm test:coverage

Local Testing

1. Build the project:

   pnpm build

2. Link locally:

   npm link

3. Configure your MCP client to use the local build

4. Test with an MCP Inspector or client

Examples

See the examples directory for real-world use cases:

• Developer Onboarding
• Database Configuration
• Deployment Approval

Architecture

src/
├── index.ts              # CLI entry point
├── server.ts             # MCP server setup
├── stdio.ts              # Stdio transport
├── types.ts              # TypeScript type definitions
├── elicitation/
│   ├── core.ts           # Core elicitation logic
│   └── schemas.ts        # Schema builders
└── tools/
    ├── index.ts          # Tool registry
    └── render_question.ts # Main tool implementation

For AI Agents

See AGENTS.md for detailed guidance on using this tool effectively in AI workflows.

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines and submit a PR.

Related Projects

• MCP Specification
• MCP TypeScript SDK
• mcp-elicit - Reference implementation