Tool Orchestration with Model Context Protocol

Pattern: Simple Tool Execution with Vercel AI SDK

// Vercel AI SDK - Basic tool usage
import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

// Define a simple tool
const weatherTool = tool({
  description: 'Get current weather for a location',
  parameters: z.object({
    location: z.string().describe('City name or zip code'),
    units: z.enum(['celsius', 'fahrenheit']).default('fahrenheit'),
  }),
  execute: async ({ location, units }) => {
    // Call weather API
    const response = await fetch(
      `https://api.weather.com/current?location=${location}&units=${units}`
    );
    const data = await response.json();

    return {
      temperature: data.temp,
      conditions: data.conditions,
      humidity: data.humidity,
    };
  },
});

// Give agent access to tool
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What\'s the weather like in San Francisco?',
  tools: {
    getWeather: weatherTool,
  },
  maxSteps: 5, // Allow multi-step tool usage
});

console.log(result.text);
// Agent automatically decides to call getWeather tool
// Returns natural language response with weather data

Pattern: Tool Chaining for Complex Workflows

// Multi-tool agent for customer support
import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

// Tool 1: Search customer database
const searchCustomer = tool({
  description: 'Search for customer by email or ID',
  parameters: z.object({
    query: z.string().describe('Email or customer ID'),
  }),
  execute: async ({ query }) => {
    const customer = await db.customers.findFirst({
      where: { OR: [{ email: query }, { id: query }] },
    });
    return customer;
  },
});

// Tool 2: Get order history
const getOrderHistory = tool({
  description: 'Get order history for a customer',
  parameters: z.object({
    customerId: z.string().describe('Customer ID'),
  }),
  execute: async ({ customerId }) => {
    const orders = await db.orders.findMany({
      where: { customerId },
      orderBy: { createdAt: 'desc' },
      take: 10,
    });
    return orders;
  },
});

// Tool 3: Issue refund
const issueRefund = tool({
  description: 'Issue a refund for an order',
  parameters: z.object({
    orderId: z.string().describe('Order ID to refund'),
    amount: z.number().describe('Refund amount in dollars'),
    reason: z.string().describe('Reason for refund'),
  }),
  execute: async ({ orderId, amount, reason }) => {
    const refund = await stripe.refunds.create({
      charge: orderId,
      amount: amount * 100, // Stripe uses cents
      reason,
    });

    // Log to database
    await db.refunds.create({
      data: { orderId, amount, reason, stripeRefundId: refund.id },
    });

    return { success: true, refundId: refund.id };
  },
});

// Agent orchestrates tool usage automatically
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Customer john@example.com wants a refund for their most recent order. Issue $29.99 refund for damaged item.',
  tools: {
    searchCustomer,
    getOrderHistory,
    issueRefund,
  },
  maxSteps: 10,
});

// Agent workflow (automatic):
// 1. Calls searchCustomer({ query: 'john@example.com' })
// 2. Calls getOrderHistory({ customerId: '<customer-id>' })
// 3. Calls issueRefund({ orderId: '<order-id>', amount: 29.99, reason: 'damaged item' })
// 4. Returns natural language confirmation

Pattern: Connecting to MCP Servers

// Example: Using Supabase MCP server
// Configuration in mcp.config.json:
{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp",
      "params": {
        "features": "database,docs,debugging,development,functions,storage",
        "readonly": false
      }
    }
  }
}

// Vercel AI SDK automatically exposes MCP tools
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

// Agent now has access to ALL Supabase MCP tools:
// - Query database tables
// - Read Supabase documentation
// - Manage storage buckets
// - Deploy Edge Functions
// - etc.

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Show me all users who signed up in the last 7 days',
  // Tools from MCP servers automatically included
  maxSteps: 5,
});

// Agent will:
// 1. Use Supabase MCP query tool
// 2. Construct appropriate SQL query
// 3. Return formatted results

Pattern: Generate Tools from OpenAPI Spec

// Automatic tool generation from OpenAPI/Swagger
import { generateToolsFromOpenAPI } from '@ai-sdk/tools';

// Generate tools from OpenAPI spec
const stripeTools = await generateToolsFromOpenAPI({
  spec: 'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml',
  operations: [
    'create_customer',
    'list_customers',
    'create_payment_intent',
    'list_charges',
  ],
  auth: {
    type: 'bearer',
    token: process.env.STRIPE_SECRET_KEY,
  },
});

// Now use auto-generated tools
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Create a customer for john@example.com and charge them $99',
  tools: stripeTools,
  maxSteps: 10,
});

// Agent automatically:
// 1. Calls create_customer tool with email
// 2. Calls create_payment_intent with customer ID and amount
// 3. Returns confirmation

// Robust tool error handling
import { tool } from 'ai';
import { z } from 'zod';

const robustTool = tool({
  description: 'Production-ready tool with error handling',
  parameters: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    try {
      // Attempt operation
      const result = await externalAPI.query(query);

      // Validate result
      if (!result || !result.data) {
        return {
          success: false,
          error: 'Invalid response from API',
          message: 'The API returned an unexpected format. Please try again.',
        };
      }

      return {
        success: true,
        data: result.data,
      };
    } catch (error: any) {
      // Log error for monitoring
      console.error('Tool execution failed:', error);

      // Return structured error to agent
      if (error.code === 'TIMEOUT') {
        return {
          success: false,
          error: 'timeout',
          message: 'The operation timed out. The service may be experiencing high load.',
          retryable: true,
        };
      }

      if (error.code === 'RATE_LIMIT') {
        return {
          success: false,
          error: 'rate_limit',
          message: 'Rate limit exceeded. Please wait before retrying.',
          retryable: true,
          retryAfter: error.retryAfter,
        };
      }

      // Generic error
      return {
        success: false,
        error: 'unknown',
        message: `Operation failed: ${error.message}`,
        retryable: false,
      };
    }
  },
});

// Agent receives structured error responses and can:
// - Retry on retryable errors
// - Use alternative tools
// - Inform user about failures gracefully