Skip to main content

​
Overview

Send natural language instructions to build features, deploy apps, or modify existing code. The MCP server calls the synchronous messages endpoint and waits for the agent to finish, pause for input, error, or accept the work into the queue.
Use bilt_get_session to check queued/running workflow status and preview URLs between requests.

​
Parameters

​
string
required
The project to send the message to
  • Format: UUID
  • Example: "660e8400-e29b-41d4-a716-446655440001"
​
string
Natural language instruction for the AI agent.
  • Required for fresh requests unless answers is provided
  • Examples:
    • "Add a login screen with email and password fields"
    • "Deploy to production"
    • "Fix the undefined variable error in UserComponent"
​
string
Workflow ID from a paused questions response.
  • Format: UUID
  • Required when answers is provided
  • Copy this from the workflowId field in the paused response
​
string
JSON array of structured answers when the agent paused for clarification questions.
  • Format: [{"questionIndex": 0, "selectedOptions": ["Option A"]}]
  • Required when continuing a paused question workflow (along with projectId and workflowId)
  • You may include an optional message alongside the answers
At least one of message or answers must be provided.

​
Response

Responses vary by status. All successful responses include previewUrl and projectUrl.
​
string
required
"completed", "queued", "paused", "error", or "timeout"
​
string
Session identifier for the project
​
string
Workflow identifier for the current run
​
string
URL to preview the app in the browser
​
string
URL to open the project in the Bilt web app
​
string
Agent response text when status is "completed". Omitted when status is "queued" because the agent has accepted the work but has not started generating a response yet.
​
string
When status is "paused": "questions", "secrets", or "supabase"
​
array
Clarification questions when status is "paused" and pauseType is "questions"
​
object
Secret request details when status is "paused" and pauseType is "secrets"
​
object
Supabase connection request details when status is "paused" and pauseType is "supabase"
​
string
Error details when status is "error" or "timeout"

​
Example Usage

​
Basic Feature Addition

​
Queued Response

When another workflow is already running, Bilt can accept the message into the queue and return immediately. Keep the workflowId and call bilt_get_session for the same projectId until hasActiveWorkflows is false before sending unrelated follow-up work.

​
Paused for Questions

When the agent pauses for clarification, respond with structured answers:

​
Paused for Secrets or Supabase

When pauseType is "secrets" or "supabase", share the projectUrl with the user so they can complete the step in the Bilt web app. Do not try to supply secrets through this tool.

​
Agent Workflow Example

1

Create project

2

Build features

3

Deploy when ready

bilt_get_session

Check workflow status

bilt_get_messages

View conversation history

bilt_cancel_workflow

Stop running workflows