MCP Integration - Buena.ai API

The Buena.ai TypeScript SDK includes a built-in MCP server that enables AI assistants to directly interact with your leads and API data. This allows AI tools like Claude Desktop, Cline, and other MCP-compatible clients to manage your Buena.ai data seamlessly.

🤖 AI-Native: Built specifically for AI assistant integration using the official Model Context Protocol standard.

📦 Installation & Setup

Step 1: Install the SDK

npm install @buena/sdk

Step 2: Start the MCP Server

# If you have the SDK installed globally
npx @buena/sdk mcp

# Or if installed locally in your project
./node_modules/.bin/@buena/sdk mcp

Step 3: Configure Your AI Assistant

Add the MCP server to your AI assistant’s configuration:

{
  "mcpServers": {
    "buena": {
      "command": "npx",
      "args": ["@buena/sdk", "mcp"],
      "env": {
        "BUENA_API_KEY": "your-api-key-here"
      }
    }
  }
}

🛠️ Available MCP Tools

The MCP server exposes the following tools to AI assistants:

Lead Management Tools

`buena_list_leads`

Search and filter leads with advanced options.

Parameters:

limit (optional): Number of leads to return (default: 50, max: 100)
offset (optional): Pagination offset (default: 0)
search (optional): Search term for name/email
company (optional): Filter by company name
status (optional): Filter by status (active, inactive, contacted)
sort (optional): Sort field (created_at, updated_at, first_name, last_name)
order (optional): Sort order (asc, desc)

`buena_create_lead`

Create a new lead in your database.

Parameters:

first_name (required): Lead’s first name
last_name (required): Lead’s last name
email (required): Valid email address
company (optional): Company name
phone (optional): Phone number
linkedin_url (optional): LinkedIn profile URL
job_title (optional): Job title
location (optional): Location/city
notes (optional): Additional notes
tags (optional): Array of tags
custom_fields (optional): Custom field data as JSON object

`buena_get_lead`

Retrieve detailed information about a specific lead.

Parameters:

lead_id (required): Unique lead identifier

`buena_update_lead`

Update an existing lead’s information.

Parameters:

lead_id (required): Unique lead identifier
All other parameters are optional and same as create_lead

`buena_delete_lead`

Permanently delete a lead from your database.

Parameters:

lead_id (required): Unique lead identifier

API Key Management Tools

`buena_list_api_keys`

List all API keys for your account.

Parameters: None

`buena_create_api_key`

Create a new API key with specific permissions.

Parameters:

name (required): Descriptive name for the API key
permissions (required): Array of permission strings
description (optional): Key description
expires_at (optional): Expiration date (ISO 8601 format)

Voice Cloning Tools

`buena_list_voice_clones`

List all voice clones for the authenticated user.

Parameters: None

`buena_create_voice_clone`

Create a new voice clone using audio file uploads.

Parameters:

name (required): Descriptive name for the voice clone
description (optional): Description of the voice clone
audio_files (required): Array of audio file paths or URLs for voice training

`buena_update_voice_clone`

Update an existing voice clone’s settings.

Parameters:

voice_id (required): Unique voice clone identifier
name (optional): Updated name for the voice clone
description (optional): Updated description
settings (optional): Voice generation settings (stability, clarity, etc.)

`buena_delete_voice_clone`

Delete a voice clone from the user’s account.

Parameters:

voice_id (required): Unique voice clone identifier

`buena_generate_voice_preview`

Generate a voice preview using a voice clone.

Parameters:

voice_id (required): Voice clone identifier to use
text (required): Text to synthesize into speech
voice_settings (optional): Voice generation parameters

LinkedIn Voice Messaging Tools

`buena_send_linkedin_voice_message`

Send a LinkedIn message with optional voice message attachment.

Parameters:

profile_url (required): LinkedIn profile URL of the recipient
message (required): Text message content
voice_settings (optional): Voice message configuration
- voice_id (required): Voice clone ID to use
- voice_text (required): Text to convert to voice message
- voice_params (optional): Voice generation parameters

System Health Tools

`buena_health_check`

Check the API system status and your connection.

Parameters: None

🤖 AI Assistant Usage Examples

Lead Management Conversations

Example 1: Finding Leads

You: "Show me all leads from technology companies"

AI Assistant uses: buena_list_leads(company="technology", limit=20)

Result: Lists leads with company names containing "technology"

Example 2: Creating Leads

You: "Add John Smith from Acme Corp as a new lead. His email is john@acme.com and he's a Software Engineer"

AI Assistant uses: buena_create_lead(
  first_name="John",
  last_name="Smith",
  email="john@acme.com",
  company="Acme Corp",
  job_title="Software Engineer"
)

Result: Creates the lead and returns the new lead ID

Example 3: Lead Research

You: "Find all leads who work at startups and haven't been contacted yet"

AI Assistant uses: buena_list_leads(
  search="startup",
  status="inactive",
  limit=50
)

Result: Returns uncontacted leads from startup companies

Example 4: Voice Clone Management

You: "Create a voice clone called 'Professional Voice' and send a voice message to John Smith on LinkedIn"

AI Assistant:
1. Uses buena_create_voice_clone(name="Professional Voice", audio_files=[...])
2. Uses buena_send_linkedin_voice_message(
     profile_url="https://linkedin.com/in/johnsmith",
     message="Hi John, hope you're well!",
     voice_settings={
       "voice_id": "new-voice-id",
       "voice_text": "Hi John, hope you're having a great week!"
     }
   )

Result: Creates voice clone and sends personalized voice message

Example 5: Voice Preview Generation

You: "Generate a preview of my voice clone saying 'Hello, this is a test message'"

AI Assistant uses: buena_generate_voice_preview(
  voice_id="user-voice-id",
  text="Hello, this is a test message"
)

Result: Returns audio preview URL for testing voice quality

Advanced Workflow Examples

Lead Qualification Workflow

You: "Help me qualify leads from last week. Show me new leads and analyze their potential"

AI Assistant:
1. Uses buena_list_leads(sort="created_at", order="desc") to get recent leads
2. Analyzes each lead's company, title, and notes
3. Provides qualification recommendations
4. Optionally updates lead status using buena_update_lead()

Lead Cleanup Workflow

You: "Find and clean up duplicate leads based on email addresses"

AI Assistant:
1. Uses buena_list_leads() to get all leads
2. Identifies duplicates by email
3. Suggests which duplicates to keep/remove
4. Uses buena_delete_lead() to remove confirmed duplicates

🔧 Configuration Options

Environment Variables

Variable	Description	Required
`BUENA_API_KEY`	Your Buena.ai API key	Yes
`BUENA_API_URL`	API base URL (default: https://api.buena.ai/api/v2)	No
`MCP_SERVER_PORT`	Server port (default: auto-assigned)	No
`MCP_LOG_LEVEL`	Logging level (debug, info, warn, error)	No

Advanced Configuration

Create a buena-mcp.config.json file:

{
  "server": {
    "port": 3001,
    "logLevel": "info"
  },
  "api": {
    "baseUrl": "https://api.buena.ai/api/v2",
    "timeout": 30000,
    "retries": 3
  },
  "tools": {
    "enabled": [
      "buena_list_leads",
      "buena_create_lead",
      "buena_get_lead",
      "buena_update_lead",
      "buena_delete_lead",
      "buena_list_api_keys",
      "buena_create_api_key",
      "buena_list_voice_clones",
      "buena_create_voice_clone",
      "buena_update_voice_clone",
      "buena_delete_voice_clone",
      "buena_generate_voice_preview",
      "buena_send_linkedin_voice_message",
      "buena_health_check"
    ],
    "limits": {
      "maxLeadsPerQuery": 100,
      "maxBatchSize": 50
    }
  }
}

🔒 Security & Permissions

API Key Permissions

Ensure your API key has the necessary permissions for MCP operations:

Required Permissions:

leads:read - For listing and retrieving leads
leads:write - For creating and updating leads
leads:delete - For deleting leads (optional)
api_keys:read - For listing API keys
api_keys:write - For creating API keys (optional)
voice:create - For creating voice clones
voice:read - For listing and retrieving voice clones
voice:update - For updating voice clone settings
voice:delete - For deleting voice clones (optional)
voice:preview - For generating voice previews
linkedin:voice - For sending LinkedIn voice messages

Safe Usage Guidelines

Environment Isolation: Use separate API keys for MCP vs production
Permission Scoping: Grant only necessary permissions to MCP API keys
Access Control: Restrict MCP server access to authorized AI assistants only
Audit Logging: Monitor MCP tool usage through API logs
Rate Limiting: Be aware of API rate limits when using AI assistants

🧪 Testing the MCP Server

Manual Testing

# Start the MCP server in test mode
BUENA_API_KEY=your-test-key npx @buena/sdk mcp --test

# Check if server is responding
curl -X POST http://localhost:3001/mcp/test \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Integration Testing

// test-mcp-integration.js
import { McpClient } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function testMcpServer() {
  // Connect to MCP server
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["@buena/sdk", "mcp"],
    env: { BUENA_API_KEY: "your-test-key" },
  });

  const client = new McpClient(
    { name: "test-client", version: "1.0.0" },
    { capabilities: {} }
  );

  await client.connect(transport);

  try {
    // Test listing tools
    const tools = await client.listTools();
    console.log(
      "Available tools:",
      tools.tools.map((t) => t.name)
    );

    // Test calling a tool
    const result = await client.callTool({
      name: "buena_health_check",
      arguments: {},
    });
    console.log("Health check result:", result);

    // Test lead operations
    const leads = await client.callTool({
      name: "buena_list_leads",
      arguments: { limit: 3 },
    });
    console.log("Sample leads:", leads);
  } finally {
    await client.close();
  }
}

testMcpServer().catch(console.error);

🛠️ Troubleshooting

Common Issues

1. Server Won’t Start

Symptoms: Error: BUENA_API_KEY not found Solution:

# Set environment variable
export BUENA_API_KEY=your-api-key
npx @buena/sdk mcp

2. AI Assistant Can’t Connect

Symptoms: “MCP server not responding” Solutions:

Check API key permissions
Verify network connectivity
Check server logs: npx @buena/sdk mcp --log-level debug

3. Tool Calls Failing

Symptoms: “Permission denied” or “Invalid parameters” Solutions:

Verify API key has required permissions
Check parameter formats match API specification
Test API calls directly first

4. Rate Limiting Issues

Symptoms: “Too many requests” errors Solutions:

Implement request queuing in AI workflows
Use pagination for large data sets
Monitor API usage dashboard

Debug Mode

# Start server with debug logging
DEBUG=* BUENA_API_KEY=your-key npx @buena/sdk mcp --debug

# View detailed logs
tail -f ~/.buena/mcp-server.log

🚀 Advanced Features

Custom Tool Creation

Extend the MCP server with custom tools:

// custom-tools.ts
import { Tool } from "@modelcontextprotocol/sdk/types.js";

export const customTools: Tool[] = [
  {
    name: "buena_lead_analytics",
    description: "Generate analytics report for leads",
    inputSchema: {
      type: "object",
      properties: {
        date_range: {
          type: "string",
          description: 'Date range (e.g., "last_30_days")',
        },
        group_by: {
          type: "string",
          description: "Group by field (company, status, etc.)",
        },
      },
    },
  },
];

Batch Operations

// Batch lead creation example for AI assistants
async function batchCreateLeads(leads) {
  const results = [];
  for (const lead of leads) {
    try {
      const result = await mcpClient.callTool({
        name: "buena_create_lead",
        arguments: lead,
      });
      results.push({ success: true, result });
    } catch (error) {
      results.push({ success: false, error: error.message, lead });
    }
  }
  return results;
}

📊 Monitoring & Analytics

Usage Tracking

The MCP server automatically tracks:

Tool call frequency
Response times
Error rates
API quota usage

Integration with Monitoring Tools

// Example: Send MCP metrics to monitoring service
const mcpMetrics = {
  toolCalls: {
    buena_list_leads: 45,
    buena_create_lead: 12,
    buena_update_lead: 8,
  },
  avgResponseTime: "125ms",
  errorRate: "2.1%",
};

// Send to your monitoring service
await sendMetrics("buena-mcp", mcpMetrics);

🤝 Community & Support

Getting Help

📖 MCP Protocol Documentation: Model Context Protocol
💬 Discord: Join our community
📧 Email Support: support@buena.ai
🐛 Bug Reports: GitHub Issues

Contributing

Help improve the MCP integration:

Report Issues: Share your AI assistant integration experiences
Feature Requests: Suggest new MCP tools and capabilities
Code Contributions: Submit PRs for new tools or improvements
Documentation: Help improve examples and guides

Next Steps: After setting up MCP, try asking your AI assistant to “show me my recent leads” or “create a new lead for John from Acme Corp” to see the integration in action!

Get Started

Guides

SDKs & Tools

​📦 Installation & Setup

​Step 1: Install the SDK

​Step 2: Start the MCP Server

​Step 3: Configure Your AI Assistant

​🛠️ Available MCP Tools

​Lead Management Tools

​buena_list_leads

​buena_create_lead

​buena_get_lead

​buena_update_lead

​buena_delete_lead

​API Key Management Tools

​buena_list_api_keys

​buena_create_api_key

​Voice Cloning Tools

​buena_list_voice_clones

​buena_create_voice_clone

​buena_update_voice_clone

​buena_delete_voice_clone

​buena_generate_voice_preview

​LinkedIn Voice Messaging Tools

​buena_send_linkedin_voice_message

​System Health Tools

​buena_health_check

​🤖 AI Assistant Usage Examples

​Lead Management Conversations

​Advanced Workflow Examples

​🔧 Configuration Options

​Environment Variables

​Advanced Configuration

​🔒 Security & Permissions

​API Key Permissions

​Safe Usage Guidelines

​🧪 Testing the MCP Server

​Manual Testing

​Integration Testing

​🛠️ Troubleshooting

​Common Issues

​1. Server Won’t Start

​2. AI Assistant Can’t Connect

​3. Tool Calls Failing

​4. Rate Limiting Issues

​Debug Mode

​🚀 Advanced Features

​Custom Tool Creation

​Batch Operations

​📊 Monitoring & Analytics

​Usage Tracking

​Integration with Monitoring Tools

​🤝 Community & Support

​Getting Help

​Contributing

📦 Installation & Setup

Step 1: Install the SDK

Step 2: Start the MCP Server

Step 3: Configure Your AI Assistant

🛠️ Available MCP Tools

Lead Management Tools

`buena_list_leads`

`buena_create_lead`

`buena_get_lead`

`buena_update_lead`

`buena_delete_lead`

API Key Management Tools

`buena_list_api_keys`

`buena_create_api_key`

Voice Cloning Tools

`buena_list_voice_clones`

`buena_create_voice_clone`

`buena_update_voice_clone`

`buena_delete_voice_clone`

`buena_generate_voice_preview`

LinkedIn Voice Messaging Tools

`buena_send_linkedin_voice_message`

System Health Tools

`buena_health_check`

🤖 AI Assistant Usage Examples

Lead Management Conversations

Advanced Workflow Examples

🔧 Configuration Options

Environment Variables

Advanced Configuration

🔒 Security & Permissions

API Key Permissions

Safe Usage Guidelines

🧪 Testing the MCP Server

Manual Testing

Integration Testing

🛠️ Troubleshooting

Common Issues

1. Server Won’t Start

2. AI Assistant Can’t Connect

3. Tool Calls Failing

4. Rate Limiting Issues

Debug Mode

🚀 Advanced Features

Custom Tool Creation

Batch Operations

📊 Monitoring & Analytics

Usage Tracking

Integration with Monitoring Tools

🤝 Community & Support

Getting Help

Contributing