Skip to main content

​
Overview

The most powerful tool in the Bilt MCP arsenal. Send natural language instructions to build features, deploy apps, or modify existing code.
This tool triggers asynchronous workflows. Use bilt_get_session or bilt_get_messages to monitor progress.

​
Parameters

​
session_id
string
required
Active workflow session ID from bilt_get_session.
  • Format: UUID
  • Example: "550e8400-e29b-41d4-a716-446655440000"
  • Get it: Call bilt_get_session() first
​
message
string
required
Natural language instruction for the AI agent.
  • Min length: 1 character
  • Max length: 5000 characters
  • Be specific: Clear instructions get better results
  • Examples:
    • "Add a login screen with email and password fields"
    • "Deploy to production"
    • "Fix the undefined variable error in UserComponent"
​
wait_for_response
boolean
default:"false"
Whether to wait for workflow completion before returning.
  • false (default): Returns immediately with workflow ID
  • true: Blocks until workflow completes (up to 5 minutes)
  • Use true for: Short operations, synchronous agents
  • Use false for: Long builds, async agents

​
Response

​
session_id
string
required
Session ID for this workflow
​
workflow_started
boolean
required
Whether the workflow was successfully initiated
​
subscriber_count
integer
required
Number of active SSE subscribers (usually 0 for API calls)
​
workflow_id
string
Unique identifier for this specific workflow run
​
status
string
Current workflow status: "pending", "running", "completed", "failed"

​
Example Usage

​
Basic Feature Addition

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Add a dark mode toggle in the navigation bar"
}

​
Deployment

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Deploy to production"
}

​
Synchronous Operation

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Change button color to blue",
  "wait_for_response": true
}

​
Agent Workflow Examples

​
Pattern 1: Build and Deploy

1

Create project

Agent: bilt_create_project("todo-app")
Response: { id: "proj_abc" }
2

Get session

Agent: bilt_get_session()
Response: { session_id: "sess_xyz" }
3

Build features

Agent: bilt_send_message(
  session_id: "sess_xyz",
  message: "Create a todo list with add, delete, and complete actions"
)
Response: { workflow_started: true, status: "running" }
4

Check progress

Agent polls: bilt_get_session()
Response: { status: "building", progress: "60%" }
5

Deploy when ready

Agent: bilt_send_message(
  session_id: "sess_xyz",
  message: "Deploy to production"
)
Response: { workflow_started: true }
6

Get deployment URL

Agent: bilt_get_messages()
Response: { 
  messages: [
    { side: "ai", message: "Deployed to https://todo-app.bilt.app" }
  ]
}

​
Pattern 2: Iterative Development

User: "Create a landing page"
Agent: bilt_create_project + bilt_send_message("Create landing page")
→ Build completes

User: "Add a pricing section"
Agent: bilt_send_message("Add pricing section with 3 tiers")
→ Build completes

User: "Make the header sticky"
Agent: bilt_send_message("Make navigation bar stick to top on scroll")
→ Build completes

User: "Deploy it"
Agent: bilt_send_message("Deploy to production")
→ Returns live URL

​
Message Best Practices

✅ Good:
"Add a login form with email and password fields, 
 validation, and a 'Forgot Password' link"
❌ Too vague:
"Add login"
Instead of one huge message:
"Create a full e-commerce app with products, cart, checkout, 
 payments, admin panel, analytics..."
Break it down:
  1. "Create product listing page"
  2. "Add shopping cart functionality"
  3. "Implement checkout flow"
  4. "Integrate payment processing"
✅ Good:
"In the UserProfile component, change the avatar size to 64px 
 and add a border"
❌ Missing context:
"Change avatar size"
Trigger deployment with clear phrases:
  • "Deploy to production"
  • "Publish the app"
  • "Go live"
  • "Deploy now"

​
Understanding Workflow States

The workflow goes through these states:

pendingQueued, waiting to start

runningActively building/deploying

completedSuccessfully finished

failedError occurred, check logs

​
Monitoring Progress

Since workflows are async, poll for updates: 
// Pseudo-code
async function waitForCompletion(sessionId) {
  while (true) {
    const session = await bilt_get_session({ session_id: sessionId });
    
    if (session.status === 'completed') {
      return session;
    }
    
    if (session.status === 'failed') {
      throw new Error('Workflow failed');
    }
    
    await sleep(2000); // Poll every 2 seconds
  }
}
Alternatively, use wait_for_response: true for short operations

​
Error Handling

{
  "error": "Invalid request body",
  "details": {
    "message": "Message is required"
  }
}

​
Performance Tips

Batch related changesSend one message with multiple changes instead of multiple messages

Use async modeSet wait_for_response: false for long builds

Poll efficientlyCheck status every 2-5 seconds, not every second

Cache session IDsReuse the same session for multiple messages

​
Rate Limits

Messages100 messages per hour per project

Concurrent Workflows1 workflow per session at a time

bilt_get_session

Get session ID before sending

bilt_get_messages

View workflow history

bilt_cancel_workflow

Stop running workflows