MCP Server

MCP Server Prompts

The MCP (Model Context Protocol) Server handler supports prompts in addition to tools, enabling you to provide reusable, parameterized prompt templates through the MCP protocol.

MCP prompts allow AI clients to request and execute structured prompt templates with dynamic parameters, making it easy to standardize and share prompt patterns and context across different AI workflows.

Overview

Much like tools, Zuplo's MCP prompts work by utilizing structured API routes as prompt generators that return formatted messages for AI consumption. When an MCP client calls a prompt, your route handler returns a structured message array that the AI can use directly.

But unlike MCP tools that perform actions and return data, MCP prompts return formatted instructions or context that guide AI reasoning and responses.

Configuration

Route Configuration

Configure a route in your OpenAPI doc:

Code
 
{
  "/greeting": {
    "post": {
      "operationId": "greeting",
      "summary": "Generate a personalized greeting",
      "description": "Creates a customized greeting for a given person",
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The name of the person to greet"
                }
              },
              "required": ["name"]
            }
          }
        }
      },
      "x-zuplo-route": {
        "corsPolicy": "none",
        "handler": {
          "export": "default",
          "module": "$import(./modules/greeting)"
        }
      }
    }
  }
}

To provide MCP specific metadata for the prompt, use x-zuplo-mcp-prompt:

Code
 
"x-zuplo-mcp-prompt": {
  "name": "greeting_generator",
  "description": "Utilize this prompt to generate a personalized greeting message"
},

The x-zuplo-mcp-prompt extension supports:

• name - The identifier for the MCP prompt
• description - Description of what the prompt generates

Without x-zuplo-mcp-prompt, the MCP server will use the route's operationId as the prompt name and the summary as the prompt description.

MCP Server Handler Configuration

Add prompt configuration to your MCP Server handler options:

Code
 
{
  "paths": {
    "/mcp": {
      "post": {
        "x-zuplo-route": {
          "handler": {
            "export": "mcpServerHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "name": "example-mcp-server",
              "version": "1.0.0",
              "prompts": [
                {
                  "path": "./config/routes.oas.json",
                  "operationIds": ["greeting"]
                }
              ]
            }
          }
        }
      }
    }
  }
}

The prompts array supports:

• path - Path to the OpenAPI specification file containing prompt routes
• operationIds - Array of operation IDs to include as MCP prompts

Route Handler Implementation

Your route handler must return a structured response with a messages array containing properly formatted message objects:

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

  return {
    messages: [
      {
        role: "assistant",
        content: {
          type: "text",
          text: `Create a personalized greeting for ${name}. Make it friendly and welcoming!`,
        },
      },
    ],
  };
}

Message Structure

Each message in the messages array should follow this structure:

• role - The role of the message ("assistant", "user", or "system")
• content - The content object with:
  • type - Content type ("text" for text content)
  • text - The actual text content

For more information, review the PromptMessage type described in the MCP docs.

Multiple Messages

You can return multiple messages to create complex and dynamic templates:

Code
 
return {
  messages: [
    {
      role: "system",
      content: {
        type: "text",
        text: "You are a helpful assistant that generates personalized greetings.",
      },
    },
    {
      role: "assistant",
      content: {
        type: "text",
        text: `Create a warm greeting for ${name} in ${location}. Consider local customs and time of day.`,
      },
    },
  ],
};

Testing MCP Prompts

List Available Prompts

Use the MCP prompts/list method to see available prompts:

Code
 
curl localhost:9000/mcp \
  -X POST \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "prompts/list"
  }'

Response:

Code
 
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "prompts": [
      {
        "name": "greeting_generator",
        "description": "Generate a personalized greeting message for someone in a specific location",
        "arguments": [
          {
            "name": "name",
            "description": "The name of the person to greet",
            "required": true
          }
        ]
      }
    ]
  }
}

Execute a Prompt

Use the MCP prompts/get method to execute a prompt with parameters:

Code
 
curl localhost:9000/mcp \
  -X POST \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "prompts/get",
    "params": {
      "name": "greeting_generator",
      "arguments": {
        "name": "john"
      }
    }
  }'

Response:

Code
 
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "description": "Generate a personalized greeting message for someone in a specific location",
    "messages": [
      {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "Create a personalized greeting for john. Make it friendly and welcoming!"
        }
      }
    ]
  }
}

Best Practices

Prompt Design

• Write clear, specific prompt instructions that guide AI behavior
• Use parameter interpolation to create dynamic, contextual prompts
• Include relevant context and constraints in your prompt text
• Consider the target AI model's strengths and prompt formatting preferences

Parameter Schema

• Define comprehensive JSON schemas for prompt parameters - this must appear as a application/json request body in a POST to your route. Typically, this will point to a module that programmatically can craft the prompt.
• Include helpful descriptions for each parameter
• Mark required parameters appropriately
• Use validation to ensure parameter quality

Message Organization

• Use system messages for general behavior instructions
• Use assistant messages for specific task guidance
• Structure complex prompts as multiple focused messages
• Keep individual messages concise and purposeful