build_app
Build a Streamlit app from a natural language request.
Describe what to build, optionally include data files, and the server
handles everything: file upload, planning, code generation, and deployment.
Returns immediately with a JSON response containing app_id, status,
message, and preview_url, plus an embedded UI resource for MCP UI clients.
IMPORTANT: If your client renders MCP UI resources (iframes), do NOT
paste the preview URL — the user already sees it embedded. Otherwise,
include the preview URL so the user can open it in a browser.
ASYNC BUILD:
This tool returns immediately with a preview URL. The response includes
_meta.wait_completion: true to signal the client that the build runs in
the background. The preview iframe sends a prompt postMessage to the
parent window when the build completes (or fails).
Cancellation: If the client sends notifications/cancelled, the background
build task detects it and stops gracefully.
CLIENT _META FIELDS:
Clients can pass context via params._meta (standard MCP location):
- _meta.user_id: Client's user ID. Used as viewer_key if no explicit
viewer_key is provided.
- _meta.session_id: Client's conversation/thread ID (for tracking).
Example with _meta:
{
"name": "build_app",
"arguments": {
"request": "Create a dashboard",
"mode": "fast"
},
"_meta": {
"user_id": "user-123",
"session_id": "thread-456"
}
}
CRITICAL - viewer_key extraction:
If the user's message contains "viewer_key" followed by a value
(e.g., "viewer_key 123456" or "viewer_key=abc"), you MUST:
1. Extract the value and pass it as the viewer_key parameter
2. REMOVE it from the request text -- viewer_key is NOT an app feature
IMPORTANT - Mode Selection:
You should analyze the user's request and data to choose the appropriate mode:
- mode="fast" (DEFAULT): Direct code generation, faster execution
Use when: Clean structured data, simple clear requests, speed is priority
Examples: "Show sales by region", "Create a bar chart from this CSV"
- mode="thinking": Full reasoning with planning and validation, more robust
Use when: Data needs cleaning, complex analysis, ambiguous requests
Examples: "Analyze customer behavior patterns", "Find insights in messy data"
IMPORTANT - Language Setting:
You MUST detect the user's language and set the `language` parameter:
- Chinese -> language="zh"
- Japanese -> language="ja"
- French -> language="fr"
- German -> language="de"
- Spanish -> language="es"
- English or other -> language="en"
Args:
request: What to build (e.g., "Create a dashboard that shows sales data")
mode: Build mode. Default: "fast"
"fast" - Quick generation using unified agent (recommended for most cases)
"thinking" - Full reasoning with planning and validation (for complex cases)
language: UI language for progress page. MUST be set based on user's language.
Supported: "en", "zh", "ja", "fr", "de", "es"
app_id: Optional app ID to continue a previous app session
files: Optional list of files to upload. Each file is a dict with:
- filename: Name of the file (e.g., "data.csv")
- content: File content as string (for CSV, JSON, TXT)
- content_base64: Base64-encoded content (for binary files)
- url: URL to download from (alternative to content)
- description: Optional description of the data
viewer_key: Optional. If the user provides a viewer_key in their
message, pass it here. Groups apps under this key and
requires it to view the preview URL.
Returns:
List containing:
- TextContent with JSON: {"app_id", "name", "description", "preview_url",
"created_at", "last_activity", "thumbnail_url"}
- EmbeddedResource with UI preview page
list_app
List built apps by viewer key.
RULES:
1. Only set viewer_key if user explicitly mentioned it
- Don't use placeholder values like "unused", "null", or empty strings
2. ALWAYS detect user's language and set the language parameter
- Chinese → language="zh"
- Japanese → language="ja"
- French → language="fr"
- German → language="de"
- Spanish → language="es"
- English → language="en"
CLIENT _META FIELDS:
If _meta.user_id is provided and no explicit viewer_key is set,
_meta.user_id will be used as viewer_key automatically.
Args:
viewer_key: Optional. Only include if user mentioned a viewer key.
language: REQUIRED. Detect from user's message language.
Returns:
JSON with app list + embedded gallery UI for MCP UI clients.