Code Examples

This page provides real-world code examples that demonstrate common patterns and best practices for creating MCP tools. Each example includes the complete code and detailed explanations of how it works.

Example 1: Simple Data Transformation

This is the simplest type of tool - it takes input data, transforms it, and returns the result. No external APIs, no complex logic, just straightforward data processing.

async function execute(params, config) { const { text } = params; // Transform text to uppercase const result = text.toUpperCase(); return { success: true, data: { transformed: result } }; }

How It Works

• Extracts the parameter - Uses destructuring to get the "text" parameter from params

• Transforms the data - Converts the text to uppercase using JavaScript's toUpperCase() method

• Returns the result - Returns a structured response with the transformed data

Parameter Schema

{ "text": { "type": "string", "description": "Text to transform to uppercase", "required": true } }

When to Use This Pattern

• Simple data transformations (uppercase, lowercase, formatting)

• Calculations that don't require external data

• Data validation or sanitization

• Format conversions

Improvements You Could Add

• Input validation (check that text exists and is a string)

• Error handling (wrap in try-catch)

• Additional transformation options (lowercase, title case, etc.)

Example 2: HTTP API Call with Error Handling

This example shows how to make HTTP requests to external APIs, which is one of the most common use cases for MCP tools. It includes proper error handling and secret management.

async function execute(params, config) { try { const { city } = params; const apiKey = config.OPENWEATHER_API_KEY; // Validate inputs if (!city) { return { success: false, error: 'City parameter is required' }; } if (!apiKey) { return { success: false, error: 'OPENWEATHER_API_KEY not found in workspace secrets' }; } // Make API request const response = await fetch( `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&appid=${apiKey}` ); // Handle HTTP errors if (!response.ok) { if (response.status === 404) { return { success: false, error: `City "${city}" not found` }; } return { success: false, error: `Weather API error: ${response.status} ${response.statusText}` }; } // Parse and return data const data = await response.json(); return { success: true, data: { city: data.name, temperature: data.main.temp, condition: data.weather[0].description, humidity: data.main.humidity, windSpeed: data.wind?.speed || 0 } }; } catch (error) { return { success: false, error: `Failed to fetch weather: ${error.message}` }; } }

How It Works

• Validates inputs - Checks that required parameters and secrets are present

• Makes HTTP request - Uses fetch() to call the external API

• Handles HTTP errors - Checks response status and provides specific error messages

• Parses response - Converts JSON response to JavaScript object

• Extracts relevant data - Pulls out only the data needed, transforming it as necessary

• Error handling - Wraps everything in try-catch for unexpected errors

Key Features

• URL encoding - Uses encodeURIComponent() to safely include the city name in the URL

• Secret access - Gets API key from workspace secrets via config

• Specific error messages - Different error messages for different failure scenarios

• Data transformation - Extracts and formats only the needed data from the API response

• Optional chaining - Uses ?. to safely access nested properties that might not exist

Parameter Schema

{ "city": { "type": "string", "description": "City name to get weather for", "required": true } }

Required Workspace Secret

This tool requires a workspace secret named OPENWEATHER_API_KEY containing your OpenWeatherMap API key.

When to Use This Pattern

• Fetching data from REST APIs

• Integrating with external services

• Retrieving real-time information

• Any tool that needs to access external data

Example 3: Data Processing and Calculations

This example demonstrates how to process arrays of data and perform calculations. It shows common data processing patterns you'll use in many tools.

async function execute(params, config) { try { const { numbers } = params; // Validate input if (!numbers || !Array.isArray(numbers)) { return { success: false, error: 'Numbers parameter must be an array' }; } if (numbers.length === 0) { return { success: false, error: 'Numbers array cannot be empty' }; } // Validate all elements are numbers if (!numbers.every(n => typeof n === 'number' && !isNaN(n))) { return { success: false, error: 'All elements in numbers array must be valid numbers' }; } // Calculate statistics const sum = numbers.reduce((a, b) => a + b, 0); const avg = sum / numbers.length; const max = Math.max(...numbers); const min = Math.min(...numbers); // Calculate median const sorted = [...numbers].sort((a, b) => a - b); const mid = Math.floor(sorted.length / 2); const median = sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid]; return { success: true, data: { count: numbers.length, sum, average: Math.round(avg * 100) / 100, // Round to 2 decimal places min, max, median: Math.round(median * 100) / 100 } }; } catch (error) { return { success: false, error: `Calculation error: ${error.message}` }; } }

How It Works

• Validates array input - Ensures the parameter is an array and not empty

• Validates array contents - Checks that all elements are valid numbers

• Performs calculations - Uses JavaScript array methods and Math functions

• Calculates multiple statistics - Sum, average, min, max, and median

• Formats results - Rounds decimal values for readability

Key Features

• Array validation - Comprehensive validation ensures data quality

• Array methods - Uses reduce(), every(), and sort() for data processing

• Spread operator - Uses [...numbers] to create a copy before sorting (doesn't mutate original)

• Median calculation - Shows how to calculate more complex statistics

• Rounding - Formats numbers for better readability

Parameter Schema

{ "numbers": { "type": "array", "description": "Array of numbers to calculate statistics for", "required": true, "items": { "type": "number" } } }

When to Use This Pattern

• Statistical calculations

• Data aggregation

• Array processing and transformation

• Mathematical operations on datasets

Example 4: Parameter Validation and Data Processing

This example shows comprehensive parameter validation and how to handle optional parameters with defaults. It demonstrates best practices for working with user input.

async function execute(params, config) { try { const { name, age, email } = params; // Validate required parameters if (!name || typeof name !== 'string' || name.trim().length === 0) { return { success: false, error: 'Name is required and must be a non-empty string' }; } if (!email || typeof email !== 'string') { return { success: false, error: 'Email is required and must be a string' }; } // Validate email format const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailRegex.test(email)) { return { success: false, error: 'Email must be a valid email address' }; } // Validate age if provided if (age !== undefined) { if (typeof age !== 'number' || age < 0 || age > 150) { return { success: false, error: 'Age must be a number between 0 and 150' }; } } // Process and normalize data const user = { name: name.trim(), age: age !== undefined ? Math.floor(age) : null, email: email.toLowerCase().trim() }; // Additional processing could go here // (e.g., save to database, send to API, etc.) return { success: true, data: { user, processedAt: new Date().toISOString() } }; } catch (error) { return { success: false, error: `Processing error: ${error.message}` }; } }

How It Works

• Extracts parameters - Uses destructuring to get all parameters at once

• Validates required parameters - Checks that name and email exist and are the correct type

• Validates formats - Uses regex to validate email format

• Validates optional parameters - If age is provided, validates it's a reasonable number

• Normalizes data - Trims whitespace, converts email to lowercase, rounds age

• Returns processed data - Returns the cleaned and validated data

Key Features

• Comprehensive validation - Validates type, format, and business rules

• Clear error messages - Each validation failure has a specific error message

• Data normalization - Cleans and standardizes input data

• Optional parameter handling - Shows how to handle optional parameters with defaults

• Type checking - Explicitly checks types to prevent errors

Parameter Schema

{ "name": { "type": "string", "description": "User's full name", "required": true }, "email": { "type": "string", "description": "User's email address", "required": true, "format": "email" }, "age": { "type": "number", "description": "User's age in years", "required": false, "minimum": 0, "maximum": 150 } }

When to Use This Pattern

• User input processing

• Data validation and sanitization

• Form processing

• Any tool that accepts user-provided data

Example 5: Using Workspace Secrets

This example demonstrates how to securely access and use workspace secrets. It shows the proper pattern for API authentication and configuration management.

async function execute(params, config) { try { // Access secrets from config const apiKey = config.MY_API_KEY; const apiUrl = config.API_BASE_URL; // Validate that secrets exist if (!apiKey) { return { success: false, error: 'MY_API_KEY not found in workspace secrets. Please add it to your workspace settings.' }; } if (!apiUrl) { return { success: false, error: 'API_BASE_URL not found in workspace secrets. Please add it to your workspace settings.' }; } // Validate API URL format try { new URL(apiUrl); } catch { return { success: false, error: 'API_BASE_URL must be a valid URL' }; } // Make authenticated API request const response = await fetch(`${apiUrl}/endpoint`, { method: 'GET', headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }); // Handle response if (!response.ok) { return { success: false, error: `API request failed: ${response.status} ${response.statusText}` }; } const data = await response.json(); return { success: true, data: data }; } catch (error) { return { success: false, error: `Request failed: ${error.message}` }; } }

How It Works

• Accesses secrets - Gets API key and base URL from workspace secrets

• Validates secrets exist - Checks that required secrets are configured

• Validates secret format - Validates that the API URL is a valid URL

• Uses secrets securely - Includes API key in request headers

• Makes authenticated request - Uses the secrets to authenticate with the API

Key Features

• Secret validation - Checks that secrets exist before using them

• Helpful error messages - Tells users exactly what secrets are missing

• URL validation - Validates that URLs are properly formatted

• Secure usage - Never logs or exposes secrets in error messages

• Flexible configuration - Allows API URL to be configured via secrets

Required Workspace Secrets

• MY_API_KEY - The API key for authentication

• API_BASE_URL - The base URL for the API (e.g., "https://api.example.com")

When to Use This Pattern

• Any tool that needs to authenticate with external APIs

• Tools that need configuration values

• Tools that connect to databases or services

• Any tool that uses sensitive credentials

Security Best Practices

• Never hardcode secrets - Always use workspace secrets

• Validate secrets exist - Check before using to provide clear error messages

• Don't log secrets - Never use console.log with secret values

• Don't expose in errors - Error messages should never include secret values

• Use descriptive secret names - Name secrets clearly so it's obvious what they're for

Example 6: Complete Tool with All Best Practices

This example combines all the patterns above into a complete, production-ready tool that demonstrates best practices for error handling, validation, API calls, and data processing.

async function execute(params, config) { try { // 1. Validate required parameters const { customerId, includeOrders } = params; if (!customerId) { return { success: false, error: 'customerId parameter is required' }; } if (typeof customerId !== 'string' && typeof customerId !== 'number') { return { success: false, error: 'customerId must be a string or number' }; } // 2. Check for required secrets const apiKey = config.CUSTOMER_API_KEY; const apiBaseUrl = config.CUSTOMER_API_BASE_URL || 'https://api.example.com'; if (!apiKey) { return { success: false, error: 'CUSTOMER_API_KEY not found in workspace secrets' }; } // 3. Build API request const url = `${apiBaseUrl}/customers/${encodeURIComponent(customerId)}`; const headers = { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' }; // Add query parameters if needed const queryParams = includeOrders ? '?includeOrders=true' : ''; // 4. Make API request const response = await fetch(`${url}${queryParams}`, { method: 'GET', headers: headers }); // 5. Handle HTTP errors if (!response.ok) { if (response.status === 404) { return { success: false, error: `Customer with ID ${customerId} not found` }; } if (response.status === 401) { return { success: false, error: 'Authentication failed. Please check your API key.' }; } return { success: false, error: `API error: ${response.status} ${response.statusText}` }; } // 6. Parse response const customerData = await response.json(); // 7. Process and format data const result = { customer: { id: customerData.id, name: customerData.name, email: customerData.email, status: customerData.status }, fetchedAt: new Date().toISOString() }; // Conditionally include orders if requested if (includeOrders && customerData.orders) { result.orders = customerData.orders.map(order => ({ id: order.id, date: order.date, total: order.total })); } // 8. Return success return { success: true, data: result }; } catch (error) { // 9. Handle unexpected errors console.error('Unexpected error in customer lookup:', error); return { success: false, error: `An unexpected error occurred: ${error.message}` }; } }

What This Example Demonstrates

• Comprehensive validation - Validates all inputs thoroughly

• Secret management - Properly accesses and validates secrets

• URL construction - Safely builds URLs with encoding

• HTTP error handling - Handles different HTTP status codes specifically

• Data processing - Transforms and formats API response data

• Conditional logic - Includes optional data based on parameters

• Error logging - Logs errors for debugging without exposing secrets

• Structured returns - Returns consistent, well-formatted data

Parameter Schema

{ "customerId": { "type": "string", "description": "Unique identifier for the customer", "required": true }, "includeOrders": { "type": "boolean", "description": "Whether to include order history in the response", "required": false, "default": false } }

This example represents a production-ready tool that you can use as a template for building your own tools. It demonstrates all the patterns and best practices discussed throughout this documentation.

Summary: Key Patterns to Remember

• Always validate inputs - Check that required parameters exist and are the correct type

• Check for secrets - Validate that required secrets exist before using them

• Handle errors gracefully - Use try-catch and provide clear error messages

• Use async/await - Makes asynchronous code readable and maintainable

• Return structured data - Always return { success, data } or { success, error }

• Encode URLs safely - Use encodeURIComponent() for URL parameters

• Never expose secrets - Don't log or include secrets in error messages

• Process data consistently - Transform and format data before returning it

Following these patterns will help you create reliable, maintainable tools that work well with AI assistants and provide a good user experience.