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

# MCP Tools Overview

> 7 tools for complete native mobile application lifecycle management

## Available Tools

Bilt MCP Server provides 7 tools that enable AI agents to autonomously create, build, and deploy native mobile applications.

<CardGroup cols={2}>
  <Card title="bilt_list_projects" icon="list" href="/docs/api-reference/bilt_list_projects">
    List all projects for authenticated user
  </Card>

  <Card title="bilt_get_project" icon="magnifying-glass" href="/docs/api-reference/bilt_get_project">
    Get detailed project information
  </Card>

  <Card title="bilt_create_project" icon="plus" href="/docs/api-reference/bilt_create_project">
    Create a new project
  </Card>

  <Card title="bilt_get_session" icon="clock" href="/docs/api-reference/bilt_get_session">
    Get current session and workflow status
  </Card>

  <Card title="bilt_send_message" icon="paper-plane" href="/docs/api-reference/bilt_send_message">
    Send build instructions or answer agent questions
  </Card>

  <Card title="bilt_cancel_workflow" icon="xmark" href="/docs/api-reference/bilt_cancel_workflow">
    Cancel running workflows
  </Card>

  <Card title="bilt_get_messages" icon="message" href="/docs/api-reference/bilt_get_messages">
    Retrieve conversation history
  </Card>
</CardGroup>

## Tool Categories

### Project Management

Tools for creating and managing native mobile application projects.

* **bilt\_list\_projects** - Discover existing projects
* **bilt\_get\_project** - Get project details and status
* **bilt\_create\_project** - Initialize new projects

### Workflow Execution

Tools for building and deploying native mobile applications.

* **bilt\_send\_message** - Execute build/deploy actions or answer clarification questions
* **bilt\_get\_session** - Monitor queued/running workflow progress and preview URLs
* **bilt\_get\_messages** - Review conversation history

<Info>
  `bilt_send_message` may return `status: "queued"` when another workflow is already running. Use `bilt_get_session` with the same `projectId` until `hasActiveWorkflows` is false before sending unrelated follow-up work.
</Info>

### Workflow Control

Tools for managing long-running operations.

* **bilt\_cancel\_workflow** - Stop unwanted operations

## Common Patterns

### Pattern 1: Create and Deploy

```mermaid theme={null}
graph LR
    A[bilt_create_project] --> B[bilt_send_message: build]
    B --> C[bilt_send_message: deploy]
    C --> D[Live URL]
```

### Pattern 2: Modify Existing

```mermaid theme={null}
graph LR
    A[bilt_list_projects] --> B[bilt_get_project]
    B --> C[bilt_send_message: add feature]
    C --> D[Updated App]
```

### Pattern 3: Debug and Fix

```mermaid theme={null}
graph LR
    A[bilt_get_session] --> B[bilt_get_messages]
    B --> C[bilt_send_message: fix]
    C --> D[Resolved]
```

## Tool Selection Guide

<Tabs>
  <Tab title="Discovery">
    **When to use:**

    * Agent doesn't know what projects exist
    * Need to find a specific project
    * Listing all user projects

    **Tools:**

    * `bilt_list_projects` - Get all projects
    * `bilt_get_project` - Get specific project details
  </Tab>

  <Tab title="Creation">
    **When to use:**

    * Starting a new native mobile application
    * Need a fresh project
    * Initializing from template

    **Tools:**

    * `bilt_create_project` - Create new project
  </Tab>

  <Tab title="Building">
    **When to use:**

    * Adding features
    * Modifying code
    * Deploying to production

    **Tools:**

    * `bilt_send_message` - Execute build actions
    * `bilt_get_session` - Check queued/running progress
  </Tab>

  <Tab title="Monitoring">
    **When to use:**

    * Checking build status
    * Reviewing logs
    * Debugging issues

    **Tools:**

    * `bilt_get_session` - Current status
    * `bilt_get_messages` - Full history
  </Tab>

  <Tab title="Control">
    **When to use:**

    * Want to stop current build
    * Managing long operations

    **Tools:**

    * `bilt_cancel_workflow` - Stop running workflow
  </Tab>
</Tabs>

## Authentication

All tools require authentication via Bearer token:

```json theme={null}
{
  "Authorization": "Bearer bilt_live_YOUR_TOKEN_HERE"
}
```

<Info>
  Tokens are configured at the MCP client level, not per-tool invocation.
</Info>

## Rate Limits

<ParamField path="limit" type="number" default="100">
  100 requests per minute per API key
</ParamField>

<ParamField path="headers" type="object">
  Response includes rate limit headers:

  * `X-RateLimit-Limit`: Total limit
  * `X-RateLimit-Remaining`: Remaining requests
  * `X-RateLimit-Reset`: Unix timestamp for reset
</ParamField>

<Warning>
  Exceeding rate limits returns `429 Too Many Requests`. Wait for the reset time before retrying.
</Warning>

## Error Handling

All tools use JSON-RPC 2.0 error responses:

<ResponseField name="jsonrpc" type="string" required>
  Always `"2.0"`
</ResponseField>

<ResponseField name="id" type="string | number | null" required>
  Matches the request ID, or `null` when the request could not be parsed
</ResponseField>

<ResponseField name="error" type="object" required>
  JSON-RPC error object

  <Expandable title="Error Object">
    <ResponseField name="code" type="number" required>
      JSON-RPC error code
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Human-readable error message
    </ResponseField>

    <ResponseField name="data" type="object" optional>
      Additional error context from validation or upstream API responses
    </ResponseField>
  </Expandable>
</ResponseField>

### Common Error Codes

| JSON-RPC code | HTTP status | Meaning                  | Solution                               |
| ------------- | ----------- | ------------------------ | -------------------------------------- |
| `-32700`      | 400         | Parse error              | Check JSON syntax                      |
| `-32600`      | 400         | Invalid request          | Include the required JSON-RPC envelope |
| `-32601`      | 404         | Method or tool not found | Check method and tool names            |
| `-32602`      | 400         | Invalid params           | Check required parameters and formats  |
| `-32603`      | 500         | Internal error           | Retry or contact support               |
| `-32001`      | 401         | Authentication required  | Verify API token                       |
| `-32003`      | 403         | Forbidden                | Check project ownership                |
| `-32004`      | 404         | Not found                | Verify project ID                      |
| `-32005`      | 429         | Rate limited             | Wait and retry                         |

## Next Steps

<CardGroup cols={2}>
  <Card title="Tool Reference" icon="book" href="/docs/api-reference/bilt_list_projects">
    Detailed docs for each tool
  </Card>
</CardGroup>