Other MCP Clients

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.

If your client isn’t listed in our integration guides, follow these generic instructions.

Connection Details

Every MCP client needs these core details:

string

required

https://mcp.bilt.me/mcp/sse

For HTTP transport: https://mcp.bilt.me/mcp

string

required

sse (Server-Sent Events) - RecommendedAlternative: http (HTTP POST)

string

required

Bearer token in Authorization headerFormat: Bearer bilt_live_YOUR_TOKEN_HERE

Standard Configuration Format

Most MCP clients use this JSON structure:

{
  "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:

{
  "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:

{
  "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:

{
  "headers": {
    "Authorization": "Bearer bilt_live_YOUR_TOKEN"
  }
}

Environment Variable

Reference tokens from environment:

{
  "headers": {
    "Authorization": "Bearer ${BILT_API_TOKEN}"
  }
}

Then set:

export BILT_API_TOKEN="bilt_live_YOUR_TOKEN"

Token File

Some clients support reading from files:

{
  "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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bilt_list_projects",
    "arguments": {}
  }
}

Create Project

{
  "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

{
  "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:

{
  "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

Request Limit100 requests per minute per token

Response Headers

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Handling Rate Limits

When you receive a 429 response:

Check Retry-After header
Wait specified seconds
Retry request

Example:

{
  "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:

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

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:

{
  "mcpServers": {
    "bilt": {
      "transport": { "..." },
      "debug": true,
      "logLevel": "verbose"
    }
  }
}

Check Connection

Verify URL is accessible
Test authentication
Check firewall rules
Review client logs

Common Issues

Connection refused

Cause: Network or firewall issueSolution:

Check internet connection
Test from different network
Verify port 443 is open

Invalid token

Cause: Token format or expirationSolution:

Verify format: bilt_live_...
Check for extra spaces
Regenerate token

Tools not discovered

Cause: Client not calling tool discoverySolution:

Check client supports MCP tools
Manually list tools via API
Update client to latest version

Security Best Practices

Never expose tokensDon’t commit to git or share publicly

Use environment variablesStore tokens outside config files

Rotate regularlyGenerate new tokens every 90 days

Restrict permissionsUse separate tokens per environment

Example Configurations

Python Client

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

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

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:

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

API Reference

Complete tool documentation

​Overview

​Connection Details

​Standard Configuration Format

​Transport Options

​SSE Transport (Recommended)

​HTTP Transport (Alternative)

​Authentication Methods

​Bearer Token (Standard)

​Environment Variable

​Token File

​Tool Discovery

​Manual Tool Invocation

​List Projects

​Create Project

​Send Message

​Error Handling

​Standard Error Responses

​Common Error Codes

​Rate Limits

​Handling Rate Limits

​Testing Connection

​cURL Test

​Health Check

​Client-Specific Considerations

​Desktop Applications

​Web Applications

​CLI Tools

​IDE Extensions

​Debugging

​Enable Verbose Logging

​Check Connection

​Common Issues

​Security Best Practices

​Example Configurations

​Python Client

​JavaScript Client

​Go Client

​Need Help?

API Reference

Overview

Connection Details

Standard Configuration Format

Transport Options

SSE Transport (Recommended)

HTTP Transport (Alternative)

Authentication Methods

Bearer Token (Standard)

Environment Variable

Token File

Tool Discovery

Manual Tool Invocation

List Projects

Create Project

Send Message

Error Handling

Standard Error Responses

Common Error Codes

Rate Limits

Handling Rate Limits

Testing Connection

cURL Test

Health Check

Client-Specific Considerations

Desktop Applications

Web Applications

CLI Tools

IDE Extensions

Debugging

Enable Verbose Logging

Check Connection

Common Issues

Security Best Practices

Example Configurations

Python Client

JavaScript Client

Go Client

Need Help?