┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   VOISA Agent   │────▶│   MCP Server    │────▶│  External Tool  │
│                 │◀────│                 │◀────│                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
      Request              Process                   Execute
      Response             Validate                  Return

Name: "Calendar Integration Server"
Description: "Manages appointment bookings and calendar operations"
URL: https://api.yourservice.com/mcp

{
  "transport": "http",
  "url": "https://api.example.com/mcp"
}

{
  "transport": "http",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

{
  "transport": "http",
  "url": "https://api.example.com/mcp",
  "auth": {
    "type": "oauth2",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }
}

{
  "name": "Google Calendar MCP",
  "transport": "http",
  "url": "https://mcp-google-calendar.voisa.ai",
  "auth": {
    "type": "oauth2",
    "scopes": ["calendar.events"]
  }
}

User: "I want to book an appointment for next Tuesday at 2 PM"
Agent: [Uses createEvent tool]
Agent: "I've booked your appointment for Tuesday at 2 PM.
        You'll receive a confirmation email shortly."

{
  "name": "Salesforce MCP",
  "transport": "http",
  "url": "https://mcp-salesforce.voisa.ai",
  "auth": {
    "type": "oauth2",
    "instance_url": "https://yourinstance.salesforce.com"
  }
}

{
  "name": "Database MCP",
  "transport": "http",
  "url": "https://mcp-database.yourcompany.com",
  "config": {
    "connection_string": "postgresql://user:pass@host/db",
    "ssl": true
  }
}

{
  "name": "Stripe MCP",
  "transport": "http",
  "url": "https://mcp-stripe.voisa.ai",
  "auth": {
    "api_key": "sk_live_..."
  }
}

{
  "name": "bookAppointment",
  "description": "Books an appointment in the calendar system",
  "parameters": {
    "date": {
      "type": "string",
      "description": "Date in YYYY-MM-DD format",
      "required": true
    },
    "time": {
      "type": "string",
      "description": "Time in HH:MM format",
      "required": true
    },
    "duration": {
      "type": "integer",
      "description": "Duration in minutes",
      "default": 30
    },
    "customer_name": {
      "type": "string",
      "required": true
    },
    "service": {
      "type": "string",
      "enum": ["consultation", "treatment", "follow-up"]
    }
  },
  "returns": {
    "type": "object",
    "properties": {
      "booking_id": "string",
      "confirmation_url": "string",
      "status": "string"
    }
  }
}

const express = require('express');
const app = express();

// MCP endpoint
app.post('/mcp/tools/bookAppointment', async (req, res) => {
  const { date, time, duration, customer_name, service } = req.body;

  try {
    // Your booking logic here
    const booking = await calendarAPI.createBooking({
      date,
      time,
      duration,
      customer_name,
      service
    });

    res.json({
      success: true,
      booking_id: booking.id,
      confirmation_url: booking.url,
      status: "confirmed"
    });
  } catch (error) {
    res.json({
      success: false,
      error: error.message
    });
  }
});

// Tool discovery endpoint
app.get('/mcp/tools', (req, res) => {
  res.json({
    tools: [{
      name: "bookAppointment",
      description: "Books appointments",
      // ... full tool definition
    }]
  });
});

{
  "bookAppointment": {
    "enabled": true,
    "permissions": {
      "max_bookings_per_call": 1,
      "allowed_services": ["consultation", "follow-up"],
      "advance_booking_days": 30
    },
    "defaults": {
      "duration": 30,
      "send_confirmation": true
    }
  }
}

You have access to the following tools:

1. bookAppointment: Use this to schedule appointments
   - Ask for preferred date and time
   - Confirm customer details
   - Specify service type

2. checkAvailability: Check available time slots
   - Use before suggesting times
   - Offer multiple options

3. cancelAppointment: Cancel existing bookings
   - Require booking ID or customer details
   - Confirm cancellation

Always confirm important details before using tools.
After tool execution, clearly communicate the result.

User: "I want to book an appointment"
Agent: "I'd be happy to help. What date works for you?"
User: "Next Monday"
Agent: "What time would you prefer?"
User: "2 PM"
Agent: [Executes bookAppointment tool]
Agent: "Perfect! I've booked your appointment for Monday at 2 PM."

User: "Book me for tomorrow at 3 PM"
Agent: [Tool returns error: slot unavailable]
Agent: "I apologize, but 3 PM tomorrow is not available.
        Would 2 PM or 4 PM work instead?"

Problem: Tools not appearing
Solution:
1. Check server URL
2. Verify authentication
3. Test discovery endpoint
4. Check network connectivity

Problem: 401/403 errors
Solution:
1. Verify credentials
2. Check token expiration
3. Confirm permissions
4. Review auth headers

Problem: Tool returns errors
Solution:
1. Validate parameters
2. Check server logs
3. Test manually
4. Review error messages

Problem: Tools timing out
Solution:
1. Increase timeout settings
2. Optimize server performance
3. Implement async handling
4. Add retry logic

{
  "batch": [
    {
      "tool": "checkAvailability",
      "params": { "date": "2025-01-20" }
    },
    {
      "tool": "bookAppointment",
      "params": { "slot": "${result[0].available_slots[0]}" }
    },
    {
      "tool": "sendConfirmation",
      "params": { "booking_id": "${result[1].id}" }
    }
  ]
}

{
  "tool": "processBooking",
  "conditions": {
    "if": "availability.exists",
    "then": "bookAppointment",
    "else": "addToWaitlist"
  }
}

{
  "webhooks": {
    "onToolSuccess": "https://your-app.com/webhook/success",
    "onToolError": "https://your-app.com/webhook/error",
    "onTimeout": "https://your-app.com/webhook/timeout"
  }
}