Zuplo MCP Server Getting Started

Getting Started

1. Set up your APIs in Zuplo using OpenAPI specifications
2. Add the MCP Server Handler to a route
3. Configure your server name, version, and which APIs to expose as tools
4. Deploy your project to make the MCP tools available
5. Connect your AI systems to the MCP server endpoint

Read the full technical documentation on the MCP Server Handler

2. MCP Custom Tools: Programmable AI Tools

For more complex scenarios, use MCP Custom Tools to create sophisticated AI tools with custom business logic, multi-step workflows, and programmatic control using OpenAPI specifications and custom handler functions.

Key Features

• OpenAPI Standard: Define tools using standard OpenAPI 3.1 specifications
• Custom Logic: Implement complex business workflows that go beyond simple API calls to enable powerful AI workloads
• Multi-Step Operations: Chain multiple API calls, data transformations, and conditional logic
• Type Safety: Built-in JSON Schema validation for inputs and outputs
• Runtime Integration: Full access to your gateway through context.invokeRoute()

Example Use Case

The following shows a powerful workflow that can enable an AI agent to interface with a process ordering system: instead of an agent calling each of your APIs manually, this workflow can be used as a single "aggregate" process to validate the provided customer, check that items are in stock, determine pricing, and place orders for those items.

OpenAPI Tool Definition:

Code
 
{
  "/process-order": {
    "post": {
      "summary": "Process customer order",
      "description": "Process a customer order with inventory validation and pricing",
      "operationId": "processCustomerOrder",
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["customerId", "orderNum"],
              "properties": {
                "customerId": {
                  "type": "string",
                  "description": "Unique customer identifier"
                },
                "orderNum": {
                  "type": "number",
                  "description": "Order number to process"
                }
              }
            }
          }
        }
      },
      "x-zuplo-route": {
        "handler": {
          "export": "default",
          "module": "$import(./modules/process-order)"
        }
      }
    }
  }
}

Custom Handler Implementation:

Code
 
// modules/process-order.ts
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const args = await request.json();

  // 1. Validate customer exists and is active
  const customerRes = await context.invokeRoute(
    `/customers/${args.customerId}`,
  );
  if (!customerRes.ok) {
    throw new Error("Customer not found or inactive");
  }
  const customer = await customerRes.json();

  // 2. Check the customer's order
  const orderResponse = await context.invokeRoute(`/orders/${args.orderNum}`);

  if (!orderResponse.ok) {
    throw new Error("Order not found");
  }
  const order = await orderResponse.json();

  // 3. Return structured response
  return {
    orderNum: order.id,
    items: order.items,
    status: "processed",
    customerId: args.customerId,
  };
}

Getting Started with Custom Tools

1. Create an OpenAPI specification defining your tools as POST endpoints
2. Implement custom handler functions for complex business logic
3. Configure the MCP Server Handler with your OpenAPI specification
4. Deploy and test with MCP clients

Read the full documentation on MCP Custom Tools