Skip to main content

​
Overview

Follow these best practices to build reliable, efficient, and user-friendly integrations.

​
Tool Design

​
Clear Naming

Use descriptive tool names that explain what they do: 
send_email
create_customer
get_order_status
update_inventory

​
Detailed Descriptions

Write clear descriptions that help the AI understand when to use each tool: 
{
  "name": "send_email",
  "description": "Send an email message to one or more recipients. Use this when the user asks to send, email, or message someone. Supports attachments and CC/BCC."
}

​
Parameter Documentation

Document all parameters with types and descriptions: 
{
  "parameters": {
    "email": {
      "type": "string",
      "required": true,
      "description": "Recipient email address (e.g., john@example.com)"
    },
    "subject": {
      "type": "string",
      "required": true,
      "description": "Email subject line"
    },
    "body": {
      "type": "string",
      "required": true,
      "description": "Email body content (supports HTML)"
    },
    "cc": {
      "type": "array",
      "required": false,
      "description": "CC recipients (optional, array of email addresses)"
    }
  }
}

​
Authentication

​
Secure Credentials

Never expose credentials in code or logs: 
// Store in environment variables
const apiKey = process.env.API_KEY;

// Or use BoostGPT's auth management
// Dashboard -> MCP Servers -> Settings

​
Rotate Regularly

Update API keys and tokens periodically:
  • API Keys: Rotate every 90 days
  • OAuth Tokens: Refresh before expiration
  • Passwords: Change quarterly

​
Minimal Permissions

Request only the permissions your integration needs: 
# Good: Specific scopes
scopes:
  - read:users
  - write:contacts

# Bad: Over-privileged
scopes:
  - admin
  - full_access

​
Error Handling

​
Return Clear Errors

Provide helpful error messages: 
{
  "success": false,
  "error": "Customer not found: No customer with email john@example.com",
  "code": "CUSTOMER_NOT_FOUND"
}

​
Handle Rate Limits

Respect API rate limits: 
// Check rate limits
if (rateLimitExceeded()) {
  return {
    success: false,
    error: "Rate limit exceeded. Try again in 60 seconds.",
    retryAfter: 60
  };
}

// Implement exponential backoff
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

​
Validate Inputs

Check all inputs before making API calls: 
function validateEmail(email) {
  if (!email) {
    return { valid: false, error: "Email is required" };
  }
  if (!email.includes('@')) {
    return { valid: false, error: "Invalid email format" };
  }
  return { valid: true };
}

// Use in handler
const validation = validateEmail(params.email);
if (!validation.valid) {
  return { success: false, error: validation.error };
}

​
Performance

​
Fast Responses

Keep tool responses under 5 seconds: 
// Set timeouts
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);

try {
  const response = await fetch(url, {
    signal: controller.signal
  });
  return await response.json();
} catch (error) {
  if (error.name === 'AbortError') {
    return { success: false, error: "Request timeout" };
  }
  throw error;
} finally {
  clearTimeout(timeoutId);
}

​
Cache When Possible

Cache frequently accessed data: 
const cache = new Map();

async function getCustomer(id) {
  // Check cache first
  if (cache.has(id)) {
    return cache.get(id);
  }

  // Fetch from API
  const customer = await api.getCustomer(id);

  // Cache for 5 minutes
  cache.set(id, customer);
  setTimeout(() => cache.delete(id), 5 * 60 * 1000);

  return customer;
}

​
Batch Operations

Batch requests when possible: 
// Batch create
const customers = await api.createCustomers([
  { name: "John" },
  { name: "Jane" },
  { name: "Bob" }
]);

​
Testing

​
Test All Tools

Test every tool before deploying: 
// Test script
async function testTools() {
  // Test create
  const createResult = await tools.create_customer({
    name: "Test User",
    email: "test@example.com"
  });
  assert(createResult.success);

  // Test read
  const readResult = await tools.get_customer({
    id: createResult.id
  });
  assert(readResult.success);

  // Test cleanup
  await tools.delete_customer({ id: createResult.id });
}

​
Handle Edge Cases

Test error scenarios: 
// Test invalid inputs
await tools.create_customer({
  name: "",  // Empty name
  email: "invalid"  // Invalid email
});

// Test missing data
await tools.get_customer({
  id: "nonexistent"  // Customer doesn't exist
});

// Test rate limits
for (let i = 0; i < 1000; i++) {
  await tools.list_customers();  // Should handle rate limiting
}

​
Monitor Production

Check logs regularly: Dashboard -> MCP Servers -> Your Server -> Logs
  • Monitor error rates
  • Check response times
  • Track authentication issues

​
Documentation

​
Document Use Cases

Explain when to use your integration: 
## When to Use

Use this integration when you need to:
- Look up customer information
- Create and manage deals
- Send automated emails

## When NOT to Use

Don't use for:
- Bulk data exports (use database directly)
- Real-time streaming (use websockets)

​
Provide Examples

Include practical examples: 
Example 1: Customer Lookup
"Find customer john@acme.com"
-> Uses get_customer tool
-> Returns customer details

Example 2: Deal Creation
"Create a $25K deal for Acme Corp"
-> Uses create_deal tool
-> Returns deal ID

​
Keep Updated

Update documentation when you change tools:
  • New parameters
  • Changed behavior
  • Deprecated features

​
Monitoring

​
Track Usage

Monitor tool usage: Agent -> Insights -> Tool Analytics
  • Most used tools
  • Success rates
  • Response times

​
Set Alerts

Get notified of issues:
  • High error rate: >5% failures
  • Slow responses: >5 second average
  • Auth failures: Any authentication errors

​
Review Regularly

Weekly review checklist:
  • Check error logs
  • Review response times
  • Verify rate limits not exceeded
  • Update credentials if needed
  • Check for API changes

​
Next Steps

Testing Guide

Learn how to test integrations

Debugging Guide

Debug integration issues