> ## 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.

# Other MCP Clients

> Generic configuration guide for any MCP-compatible client

## Overview

Bilt MCP Server follows the standard Model Context Protocol specification and works with any MCP-compatible client. This guide covers generic configuration that applies to all clients.

<Info>
  If your client isn't listed in our integration guides, follow these generic instructions.
</Info>

## Connection Details

Every MCP client needs these core details:

<ParamField path="Server URL" type="string" required>
  ```
  https://mcp.bilt.me/mcp/sse
  ```

  For HTTP transport: `https://mcp.bilt.me/mcp`
</ParamField>

<ParamField path="Transport Type" type="string" required>
  `sse` (Server-Sent Events) - Recommended

  Alternative: `http` (HTTP POST)
</ParamField>

<ParamField path="Authentication" type="string" required>
  Bearer token in `Authorization` header

  Format: `Bearer bilt_live_YOUR_TOKEN_HERE`
</ParamField>

***

## Standard Configuration Format

Most MCP clients use this JSON structure:

```json theme={null}
{
  "mcpServers": {
    "bilt": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_YOUR_TOKEN_HERE"
        }
      }
    }
  }
}
```

***

## Transport Options

### SSE Transport (Recommended)

Server-Sent Events provide real-time updates:

```json theme={null}
{
  "transport": {
    "type": "sse",
    "url": "https://mcp.bilt.me/mcp/sse",
    "headers": {
      "Authorization": "Bearer bilt_live_YOUR_TOKEN"
    }
  }
}
```

**Pros:**

* Real-time progress updates
* Long-running workflow support
* Efficient for monitoring builds

**Use when:**

* Client supports SSE
* Need progress updates
* Monitoring long builds

### HTTP Transport (Alternative)

Standard HTTP POST requests:

```json theme={null}
{
  "transport": {
    "type": "http",
    "url": "https://mcp.bilt.me/mcp",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer bilt_live_YOUR_TOKEN",
      "Content-Type": "application/json"
    }
  }
}
```

**Pros:**

* Universal compatibility
* Simple request/response
* Works behind strict firewalls

**Use when:**

* Client doesn't support SSE
* Firewall restrictions
* Simple tool invocations

***

## Authentication Methods

### Bearer Token (Standard)

Most common authentication:

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer bilt_live_YOUR_TOKEN"
  }
}
```

### Environment Variable

Reference tokens from environment:

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer ${BILT_API_TOKEN}"
  }
}
```

Then set:

```bash theme={null}
export BILT_API_TOKEN="bilt_live_YOUR_TOKEN"
```

### Token File

Some clients support reading from files:

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer ${file:~/.bilt/token}"
  }
}
```

***

## Tool Discovery

Bilt MCP Server exposes 7 tools:

| Tool                   | Purpose                          |
| ---------------------- | -------------------------------- |
| `bilt_list_projects`   | List all projects                |
| `bilt_get_project`     | Get project details              |
| `bilt_create_project`  | Create new project               |
| `bilt_get_session`     | Get session and workflow status  |
| `bilt_send_message`    | Send message or answer questions |
| `bilt_cancel_workflow` | Cancel running workflow          |
| `bilt_get_messages`    | Get message history              |

Clients should discover these automatically via MCP's tool listing protocol.

***

## Manual Tool Invocation

If your client requires manual tool calls:

### List Projects

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bilt_list_projects",
    "arguments": {}
  }
}
```

### Create Project

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "bilt_create_project",
    "arguments": {
      "name": "my-app",
      "description": "My native mobile application",
      "visibility": "private"
    }
  }
}
```

### Send Message

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "bilt_send_message",
    "arguments": {
      "projectId": "660e8400-e29b-41d4-a716-446655440001",
      "message": "Add a login page"
    }
  }
}
```

***

## Error Handling

### Standard Error Responses

All errors follow the JSON-RPC 2.0 format:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Missing required parameter: projectId",
    "data": {
      "field": "Additional context"
    }
  }
}
```

### 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 parameter format                 |
| `-32603`      | 500         | Internal error           | Retry or contact support               |
| `-32001`      | 401         | Authentication required  | Verify API token                       |
| `-32003`      | 403         | Forbidden                | Check permissions                      |
| `-32004`      | 404         | Not found                | Verify resource exists                 |
| `-32005`      | 429         | Rate limited             | Wait and retry                         |

***

## Rate Limits

<CardGroup cols={2}>
  <Card>
    **Request Limit**

    100 requests per minute per token
  </Card>

  <Card>
    **Response Headers**

    * `X-RateLimit-Limit`
    * `X-RateLimit-Remaining`
    * `X-RateLimit-Reset`
  </Card>
</CardGroup>

### Handling Rate Limits

When you receive a `429` response:

1. Check `Retry-After` header
2. Wait specified seconds
3. Retry request

Example:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded - please slow down requests"
  }
}
```

Wait 60 seconds, then retry.

***

## Testing Connection

### cURL Test

Test basic connectivity:

```bash theme={null}
curl -X POST https://mcp.bilt.me/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

Should return list of 7 tools.

### Health Check

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://mcp.bilt.me/health
```

Should return: `{"status":"ok"}`

***

## Client-Specific Considerations

### Desktop Applications

* Config usually in user home directory
* Restart required after changes
* Check app logs for errors

### Web Applications

* Use HTTP transport (better browser support)
* Handle CORS if needed (Bilt allows all origins)
* Store tokens securely (not in frontend code)

### CLI Tools

* Support environment variables
* Allow config file path override
* Provide clear error messages

### IDE Extensions

* Project-specific configuration
* Git-ignore sensitive tokens
* Auto-reload on config change

***

## Debugging

### Enable Verbose Logging

Most clients support debug mode:

```json theme={null}
{
  "mcpServers": {
    "bilt": {
      "transport": { "..." },
      "debug": true,
      "logLevel": "verbose"
    }
  }
}
```

### Check Connection

1. Verify URL is accessible
2. Test authentication
3. Check firewall rules
4. Review client logs

### Common Issues

<AccordionGroup>
  <Accordion title="Connection refused">
    **Cause**: Network or firewall issue

    **Solution**:

    * Check internet connection
    * Test from different network
    * Verify port 443 is open
  </Accordion>

  <Accordion title="Invalid token">
    **Cause**: Token format or expiration

    **Solution**:

    * Verify format: `bilt_live_...`
    * Check for extra spaces
    * Regenerate token
  </Accordion>

  <Accordion title="Tools not discovered">
    **Cause**: Client not calling tool discovery

    **Solution**:

    * Check client supports MCP tools
    * Manually list tools via API
    * Update client to latest version
  </Accordion>
</AccordionGroup>

***

## Security Best Practices

<CardGroup cols={2}>
  <Card icon="lock">
    **Never expose tokens**

    Don't commit to git or share publicly
  </Card>

  <Card icon="key">
    **Use environment variables**

    Store tokens outside config files
  </Card>

  <Card icon="rotate">
    **Rotate regularly**

    Generate new tokens every 90 days
  </Card>

  <Card icon="shield">
    **Restrict permissions**

    Use separate tokens per environment
  </Card>
</CardGroup>

***

## Example Configurations

### Python Client

```python theme={null}
from mcp import Client

client = Client(
    url="https://mcp.bilt.me/mcp/sse",
    transport="sse",
    headers={
        "Authorization": "Bearer bilt_live_YOUR_TOKEN"
    }
)

# List tools
tools = await client.list_tools()

# Call tool
result = await client.call_tool(
    name="bilt_create_project",
    arguments={"name": "my-app"}
)
```

### JavaScript Client

```javascript theme={null}
import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient({
  transport: {
    type: 'sse',
    url: 'https://mcp.bilt.me/mcp/sse',
    headers: {
      'Authorization': 'Bearer bilt_live_YOUR_TOKEN'
    }
  }
});

// List tools
const tools = await client.listTools();

// Call tool
const result = await client.callTool({
  name: 'bilt_create_project',
  arguments: { name: 'my-app' }
});
```

### Go Client

```go theme={null}
package main

import (
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
    client := mcp.NewClient(mcp.Config{
        URL: "https://mcp.bilt.me/mcp/sse",
        Transport: "sse",
        Headers: map[string]string{
            "Authorization": "Bearer bilt_live_YOUR_TOKEN",
        },
    })
    
    // List tools
    tools, _ := client.ListTools()
    
    // Call tool
    result, _ := client.CallTool("bilt_create_project", map[string]any{
        "name": "my-app",
    })
}
```

***

## Need Help?

If your client isn't working:

1. **Check client documentation** - Verify MCP support
2. **Test with cURL** - Ensure Bilt is accessible
3. **Review logs** - Look for specific errors
4. **Contact support** - We can help configure your client

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/docs/api-reference/overview">
    Complete tool documentation
  </Card>
</CardGroup>