MCP (Model Context Protocol) API

The RocketWave Pulse Admin exposes an MCP-compatible HTTP API that allows AI assistants and agents to interact with the platform programmatically. This enables tools like Claude Desktop, Cursor IDE, and custom agents to manage workflow entities, workflows, and other resources.

Overview

The MCP implementation follows a wrapper architecture - MCP endpoints forward requests to existing API routes, inheriting all authentication, validation, and business logic without duplication.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   MCP Layer     │────▶│ Existing API    │
│ (Claude, etc.)  │     │ (Thin Wrapper)  │     │ Routes          │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Authentication

MCP endpoints require the same session cookie authentication as the regular API. The session cookie is forwarded to internal API calls.

POST /api/mcp/tools/call
Cookie: rocketwave_session=<session_token>
Content-Type: application/json

Endpoints

List Tools

Returns all available MCP tools with their input schemas.

GET /api/mcp/tools

Response:

{
  "tools": [
    {
      "name": "entities_list",
      "description": "List workflow entities with optional filtering",
      "inputSchema": {
        "type": "object",
        "properties": {
          "organizationId": { "type": "string", "description": "Organization UUID" },
          "environmentId": { "type": "string", "description": "Environment UUID" },
          "page": { "type": "number", "description": "Page number" },
          "limit": { "type": "number", "description": "Items per page" }
        },
        "required": ["organizationId"]
      }
    }
  ]
}

Call Tool

Execute an MCP tool.

POST /api/mcp/tools/call
Content-Type: application/json
Cookie: rocketwave_session=<session_token>

{
  "name": "entities_create",
  "arguments": {
    "organizationId": "uuid-here",
    "environmentId": "uuid-here",
    "name": "My Event Entity",
    "workflowEntityTypeId": "event-type-uuid",
    "condition": {
      "type": "group",
      "operator": "AND",
      "conditions": [
        {
          "type": "rule",
          "field": "message.type",
          "comparison": "equals",
          "value": "user.signup"
        }
      ]
    }
  }
}

Success Response:

{
  "content": [
    {
      "type": "text",
      "text": "{ \"id\": \"created-entity-uuid\", \"name\": \"My Event Entity\", ... }"
    }
  ],
  "isError": false
}

Error Response:

{
  "content": [
    {
      "type": "text",
      "text": "Error (400): Missing required field: organizationId"
    }
  ],
  "isError": true
}

List Resources

Returns available resource templates.

GET /api/mcp/resources

Response:

{
  "resources": [],
  "resourceTemplates": [
    {
      "uriTemplate": "rocketwave://entities/{id}",
      "name": "Workflow Entity",
      "description": "Access a workflow entity by ID",
      "mimeType": "application/json"
    },
    {
      "uriTemplate": "rocketwave://workflows/{id}",
      "name": "Workflow",
      "description": "Access a workflow configuration by ID",
      "mimeType": "application/json"
    }
  ]
}

Read Resource

Read a specific resource by URI.

POST /api/mcp/resources/read
Content-Type: application/json
Cookie: rocketwave_session=<session_token>

{
  "uri": "rocketwave://entities/entity-uuid-here"
}

Response:

{
  "uri": "rocketwave://entities/entity-uuid-here",
  "mimeType": "application/json",
  "text": "{ \"id\": \"entity-uuid\", \"name\": \"My Entity\", ... }"
}

Available Tools

Workflow Entities

Tool	Description
`entities_list`	List workflow entities with filtering
`entities_get`	Get a workflow entity by ID
`entities_create`	Create a new workflow entity
`entities_update`	Update an existing entity
`entities_delete`	Delete a workflow entity
`entities_usage_count`	Get workflows using this entity
`entities_versions`	List version history for a workflow entity
`entities_version_get`	Get a specific version of a workflow entity

Workflows

Tool	Description
`workflows_list`	List workflows
`workflows_get`	Get a workflow by ID
`workflows_create`	Create a new workflow
`workflows_update`	Update a workflow
`workflows_delete`	Delete a workflow
`workflows_trigger`	Manually trigger a workflow execution
`workflows_versions`	List version history for a workflow
`workflows_version_get`	Get a specific version of a workflow

Environments

Tool	Description
`environments_list`	List environments for an organization
`environments_get`	Get an environment by ID
`environments_create`	Create a new environment
`environments_update`	Update an environment
`environments_delete`	Delete an environment

Variables

Tool	Description
`variables_list`	List variables (values hidden)
`variables_get`	Get a variable by ID
`variables_create`	Create a variable (value encrypted)
`variables_update`	Update a variable
`variables_delete`	Delete a variable

Example: Create Variable

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'variables_create',
    arguments: {
      organizationId: 'org-uuid',
      environmentId: 'env-uuid',
      name: 'OPENAI_API_KEY',
      value: 'sk-proj-xxxxxxxxxxxx'
    }
  })
});

note

Variable values are write-only - they're never returned in responses. The variables_list and variables_get tools return variable metadata without the actual value.

Models

Tool	Description
`models_list`	List AI models
`models_get`	Get a model by ID
`models_create`	Create a new model
`models_update`	Update a model
`models_delete`	Delete a model

Example: Create Model with Token Auth

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_create',
    arguments: {
      organizationId: 'org-uuid',
      name: 'GPT-4 Turbo',
      description: 'OpenAI GPT-4 for content generation',
      modelUrl: 'https://api.openai.com/v1/chat/completions',
      token: 'sk-proj-xxxxxxxxxxxx'
    }
  })
});

Example: Create Model with Client Key/Secret Auth (AWS Bedrock)

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'models_create',
    arguments: {
      organizationId: 'org-uuid',
      name: 'Claude 3 Sonnet (Bedrock)',
      description: 'AWS Bedrock Claude model',
      modelUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-3-sonnet/invoke',
      clientKey: 'AKIAXXXXXXXXXXXX',
      secretKey: 'xxxxxxxxxxxxxxxxxxxxxxxx'
    }
  })
});

note

Model credentials are write-only. Responses include hasToken and hasClientKey boolean flags instead of actual credentials.

Organizations

Tool	Description
`organizations_list`	List organizations (filtered by access)
`organizations_get`	Get an organization by ID
`organizations_create`	Create organization (system only)
`organizations_update`	Update organization (system only)
`organizations_delete`	Delete organization (system only)

Prompt Templates

Tool	Description
`prompt_templates_list`	List prompt templates for an organization/environment
`prompt_templates_get`	Get a prompt template by ID
`prompt_templates_create`	Create a new prompt template
`prompt_templates_update`	Update a prompt template
`prompt_templates_delete`	Delete a prompt template
`prompt_templates_execute`	Execute a prompt template against its model
`prompt_templates_analyze_sentiment`	Analyze sentiment of a prompt template
`prompt_templates_versions`	List version history for a prompt template
`prompt_templates_version_get`	Get a specific version of a prompt template

Scheduled Events

Tool	Description
`scheduled_events_list`	List scheduled workflow events
`scheduled_events_get`	Get a scheduled event by ID
`scheduled_events_create`	Create a scheduled event (cron or datetime)
`scheduled_events_update`	Update a scheduled event
`scheduled_events_delete`	Delete a scheduled event

Example: Create a Cron Schedule

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'scheduled_events_create',
    arguments: {
      workflowEntityId: 'event-entity-uuid',
      workflowId: 'workflow-uuid',
      organizationId: 'org-uuid',
      environmentId: 'env-uuid',
      scheduleType: 'cron',
      cronExpression: '0 9 * * MON',  // Every Monday at 9am
      timezone: 'America/New_York'
    }
  })
});

note

Schedule status is determined by nextRunAt. Active schedules have a future timestamp; completed or disabled schedules have nextRunAt: null.

Processed Queue

Tool	Description
`processed_queue_list`	List processed workflow execution results
`processed_queue_get`	Get a specific processed queue item
`processed_queue_delete`	Delete a processed queue item

AI Assistant

Tool	Description
`assistant_chat`	Chat with the RAG-powered AI assistant for creating entities and getting help

Other Tools

Tool	Description
`entity_types_list`	List entity types (event, action, prompt)
`roles_list`	List available roles
`documentation_search`	Search documentation (RAG)
`healthcheck_list`	List healthcheck records

Security

The MCP layer inherits all security from existing API routes:

Session Authentication - Cookies are forwarded to internal API calls
RBAC Permissions - Each tool respects permission requirements (e.g., entities:create)
Organization Validation - Users can only access resources in their organizations
Environment Scoping - Resources are scoped to the specified environment
Input Validation - All inputs are validated against JSON schemas

Usage Examples

Claude Desktop Configuration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "rocketwave": {
      "url": "https://your-admin-domain.com/api/mcp",
      "headers": {
        "Cookie": "rocketwave_session=<your_session_token>"
      }
    }
  }
}

Creating a Workflow Entity

// Using fetch
const response = await fetch('https://admin.example.com/api/mcp/tools/call', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'rocketwave_session=...'
  },
  body: JSON.stringify({
    name: 'entities_create',
    arguments: {
      organizationId: 'org-uuid',
      environmentId: 'env-uuid',
      name: 'New Signup Event',
      workflowEntityTypeId: 'event-type-uuid',
      description: 'Triggers when a new user signs up',
      condition: {
        type: 'group',
        operator: 'AND',
        conditions: [
          {
            type: 'rule',
            field: 'message.type',
            comparison: 'equals',
            value: 'user.signup'
          }
        ]
      },
      script: 'return { userId: message.data.userId };'
    }
  })
});

const result = await response.json();
console.log(result.content[0].text); // Created entity JSON

Searching Documentation

const response = await fetch('https://admin.example.com/api/mcp/tools/call', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'rocketwave_session=...'
  },
  body: JSON.stringify({
    name: 'documentation_search',
    arguments: {
      query: 'How do I create a condition with multiple rules?',
      limit: 5
    }
  })
});

Using the AI Assistant

The assistant_chat tool provides a conversational interface that can create entities and answer questions:

const response = await fetch('https://admin.example.com/api/mcp/tools/call', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'rocketwave_session=...'
  },
  body: JSON.stringify({
    name: 'assistant_chat',
    arguments: {
      organizationId: 'org-uuid',
      environmentId: 'env-uuid',
      message: 'Create an event entity that triggers when a user signs up, filtering for message.type equals "user.signup"',
      history: [] // Optional: previous messages for context
    }
  })
});

const result = await response.json();
// result.content contains the assistant's response and any created entities

The assistant can:

Create workflow entities (events, prompts, actions)
Search documentation for relevant guidance
Explain platform concepts and best practices
Generate scripts with proper syntax

Error Handling

MCP responses include an isError flag to indicate failures:

HTTP Status	Meaning
200	Success (check `isError` for tool-level errors)
400	Invalid request (missing/invalid tool name or arguments)
401	Authentication required
403	Permission denied
404	Resource not found
500	Internal server error

Rate Limiting

The MCP endpoints share rate limits with the regular API. Consider implementing client-side caching and batching for high-frequency operations.

Overview​

Authentication​

Endpoints​

List Tools​

Call Tool​

List Resources​

Read Resource​

Available Tools​

Workflow Entities​

Workflows​

Environments​

Variables​

Models​

Organizations​

Prompt Templates​

Scheduled Events​

Processed Queue​

AI Assistant​

Other Tools​

Security​

Usage Examples​

Claude Desktop Configuration​

Creating a Workflow Entity​

Searching Documentation​

Using the AI Assistant​

Error Handling​

Rate Limiting​

Overview

Authentication

Endpoints

List Tools

Call Tool

List Resources

Read Resource

Available Tools

Workflow Entities

Workflows

Environments

Variables

Models

Organizations

Prompt Templates

Scheduled Events

Processed Queue

AI Assistant

Other Tools

Security

Usage Examples

Claude Desktop Configuration

Creating a Workflow Entity

Searching Documentation

Using the AI Assistant

Error Handling

Rate Limiting