Building MCP Servers

Create MCP (Model Context Protocol) servers to enable AI assistants to interact with your workflows and data.

What is MCP?

Overview

Model Context Protocol (MCP) is a standard for AI assistant integrations:

• Enables AI tools to call your APIs
• Provides context to AI models
• Standardized communication
• Secure data access

Use Cases

Build MCPs for:

• AI-powered workflow execution
• Data querying via AI
• Automated task completion
• Conversational interfaces

MCP Architecture

Components

AI Assistant <-> MCP Server <-> Your Workflows
                    |
                    +-> Authentication
                    +-> Tool Definitions
                    +-> Data Access

How It Works

1. AI assistant connects to MCP server
2. Server exposes available tools
3. AI calls tools based on user intent
4. Tools execute workflows/queries
5. Results returned to AI

Creating an MCP Server

From Dashboard

1. Go to MCP > Create Server
2. Name your server
3. Configure authentication
4. Add tools
5. Deploy

Server Configuration

name: my-workflow-mcp
description: Execute workflows via AI
version: 1.0.0

authentication:
  type: api_key
  header: X-MCP-Key

tools:
  - name: run_workflow
    description: Execute a workflow by name
    # ... tool definition

Defining Tools

Tool Structure

Each tool needs:

• name: Unique identifier
• description: What it does (AI reads this)
• parameters: Input schema
• handler: What to execute

Example Tool

tools:
  - name: get_customer
    description: Retrieve customer information by email or ID
    parameters:
      type: object
      properties:
        identifier:
          type: string
          description: Customer email or ID
        identifier_type:
          type: string
          enum: [email, id]
          description: Type of identifier provided
      required: [identifier]
    handler:
      type: workflow
      workflow_id: customer-lookup
      mapping:
        input: identifier
        type: identifier_type

Tool Types

Workflow Tool - Runs a workflow:

handler:
  type: workflow
  workflow_id: process-order

Query Tool - Queries data:

handler:
  type: query
  source: customers
  filter: true

Custom Tool - Custom code:

handler:
  type: function
  code: |
    return { result: processData(params) };

Writing Good Descriptions

For AI Understanding

Descriptions help AI choose the right tool:

Less effective:

"Gets data"

More effective:

"Retrieves detailed customer profile including contact information, purchase history, and current subscription status. Use when user asks about a specific customer."

Include Context

Tell AI:

• When to use this tool
• What data it returns
• Any limitations
• Related tools to consider

Parameter Design

Schema Definition

Use JSON Schema:

parameters:
  type: object
  properties:
    email:
      type: string
      format: email
      description: Customer email address
    include_history:
      type: boolean
      default: false
      description: Include purchase history
  required: [email]

Best Practices

1. Clear descriptions - AI interprets these
2. Sensible defaults - Reduce required params
3. Validation - Use formats and enums
4. Examples - Help AI understand format

Authentication

API Key Auth

Simple key-based:

authentication:
  type: api_key
  header: X-MCP-Key
  # Key set in deployment

OAuth Authentication

For user context:

authentication:
  type: oauth
  provider: your-oauth-config
  scopes: [read, write]

No Authentication

For public tools:

authentication:
  type: none
  # Not recommended for sensitive data

Connecting Workflows

Workflow as Handler

Map workflow inputs:

handler:
  type: workflow
  workflow_id: send-notification
  mapping:
    recipient: email
    message: message_text
    priority: urgency

Multiple Workflows

One tool can chain workflows:

handler:
  type: workflow_chain
  workflows:
    - id: validate-input
    - id: process-request
    - id: send-response

Testing MCPs

Test Interface

1. Go to MCP > Your Server
2. Click Test
3. Simulate AI request
4. View response

Test Request

{
  "tool": "get_customer",
  "parameters": {
    "identifier": "user@example.com",
    "identifier_type": "email"
  }
}

Debug Mode

Enable verbose logging:

1. Click Settings
2. Enable Debug Mode
3. See full request/response

Deployment

Publishing Server

1. Click Deploy
2. Choose environment
3. Set API keys
4. Confirm deployment

Server URL

After deployment:

https://mcp.yourapp.com/servers/my-workflow-mcp

Connect AI Assistant

Configure your AI assistant:

{
  "mcp_servers": [{
    "url": "https://mcp.yourapp.com/servers/my-workflow-mcp",
    "auth": {
      "type": "api_key",
      "key": "your-api-key"
    }
  }]
}

Error Handling

Tool Errors

Return helpful errors:

errors:
  not_found:
    message: Customer not found
    suggestion: Check email spelling or try customer ID
  rate_limited:
    message: Too many requests
    suggestion: Wait 60 seconds before retry

Graceful Degradation

Handle workflow failures:

handler:
  type: workflow
  workflow_id: main-process
  fallback:
    type: workflow
    workflow_id: fallback-process

Best Practices

1. Focused Tools

One tool = one action. Don't overload.

2. Descriptive Names

get_customer_by_email > get_data

3. Comprehensive Descriptions

Help AI understand when and how to use.

4. Validate Inputs

Catch errors before workflow execution.

5. Test Thoroughly

Test various AI interactions before deploying.

Next Steps

• MCP Servers Overview - General concepts
• MCP Widgets - UI components
• API Reference - Technical docs