@channlize/mcp

Model Context Protocol (MCP) server for Channlize - enables AI agents to understand and interact with the Channlize platform.

Overview

The Channlize MCP server provides AI agents (like Claude) with:

• Resources: Documentation, API schemas, and integration guides
• Tools: Ability to submit forms, create chat sessions, and send messages
• Prompts: Templates for common integration patterns

This package can be used both as a standalone MCP server (for Claude Desktop and other MCP clients) or as a library to build custom MCP integrations.

Installation

npm install @channlize/mcp

Quick Start

Standalone Server (Claude Desktop)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "channlize": {
      "command": "npx",
      "args": [
        "@channlize/mcp",
        "--api-key",
        "your-widget-key-here",
        "--project-id",
        "your-project-id-here"
      ]
    }
  }
}

Or using environment variables:

{
  "mcpServers": {
    "channlize": {
      "command": "npx",
      "args": ["@channlize/mcp"],
      "env": {
        "CHANNLIZE_API_KEY": "your-widget-key-here",
        "CHANNLIZE_PROJECT_ID": "your-project-id-here",
        "CHANNLIZE_BASE_URL": "https://api.channlize.com"
      }
    }
  }
}

Library Usage

import { ChannlizeMCPServer } from '@channlize/mcp';

const server = new ChannlizeMCPServer({
  name: 'my-channlize-server',
  version: '1.0.0',
  config: {
    apiKey: process.env.CHANNLIZE_API_KEY!,
    projectId: process.env.CHANNLIZE_PROJECT_ID,
    baseUrl: process.env.CHANNLIZE_BASE_URL,
  },
});

// Run with stdio transport (for MCP clients)
await server.runStdio();

// Or get the underlying Server instance for custom transports
const mcpServer = server.getServer();

Available Resources

Resources provide read-only context about Channlize:

| URI | Description | |-----|-------------| | channlize://schema/contact-form | JSON schema for contact form data structure | | channlize://schema/chat-session | JSON schema for chat session data structure | | channlize://docs/api-reference | Complete Channlize API reference documentation | | channlize://docs/quick-start | Quick start guide for using Channlize SDK | | channlize://docs/react-components | Documentation for React components and hooks |

Example Usage in Claude

Can you show me the contact form schema?

Claude will read the channlize://schema/contact-form resource to understand the data structure.

Available Tools

Tools allow AI agents to interact with Channlize:

submit_contact_form

Submit a contact form inquiry to Channlize.

Parameters:

• name (string, required): Contact's full name
• email (string, required): Contact's email address
• message (string, required): The message content
• subject (string, optional): Subject line
• customFields (object, optional): Additional custom fields
• pageUrl (string, optional): URL where form was submitted
• userAgent (string, optional): User agent string

Example:

{
  "name": "submit_contact_form",
  "arguments": {
    "name": "John Doe",
    "email": "[email protected]",
    "message": "I need help with my account",
    "subject": "Account Support"
  }
}

create_chat_session

Create a new real-time chat session.

Parameters:

• metadata (object, optional): Custom session metadata

Returns: Session ID and SSE endpoint for real-time updates

send_message

Send a message in an existing chat session.

Parameters:

• sessionId (string, required): The chat session ID
• content (string, required): Message content

get_chat_messages

Retrieve messages from a chat session.

Parameters:

• sessionId (string, required): The chat session ID
• limit (number, optional): Max messages to retrieve (default: 50)
• offset (number, optional): Number of messages to skip (default: 0)

close_chat_session

Close an active chat session.

Parameters:

• sessionId (string, required): The chat session ID to close

Available Prompts

Prompts provide templates for common integration scenarios:

integrate-contact-form

Guide for adding a Channlize contact form to a React application.

Arguments:

• framework (optional): React framework being used (e.g., Next.js, Vite)
• styling (optional): Styling approach (e.g., Tailwind, CSS Modules)

setup-live-chat

Guide for implementing the Channlize live chat widget.

Arguments:

• placement (optional): Widget placement (e.g., "page", "popup", "sidebar")

customize-styling

Guide for theming and customizing Channlize components.

handle-webhooks

Guide for integrating Channlize webhooks into custom workflows.

CLI Usage

The standalone server can be run directly from the command line:

# Using npx
npx @channlize/mcp --api-key wk_123abc --project-id proj_456def

# Or install globally
npm install -g @channlize/mcp
channlize-mcp --api-key wk_123abc --project-id proj_456def

# Using environment variables
export CHANNLIZE_API_KEY=wk_123abc
export CHANNLIZE_PROJECT_ID=proj_456def
channlize-mcp

CLI Options

--api-key <key>        Channlize API key (widget key) [required]
--project-id <id>      Channlize project ID
--base-url <url>       Channlize API base URL (default: https://api.channlize.com)
--timeout <ms>         Request timeout in milliseconds (default: 10000)
-h, --help             Show help message

Environment Variables

• CHANNLIZE_API_KEY: Your Channlize widget key
• CHANNLIZE_PROJECT_ID: Your project ID
• CHANNLIZE_BASE_URL: API base URL (optional)
• CHANNLIZE_TIMEOUT: Request timeout in ms (optional)

Example Interactions

With Claude Desktop

Once configured, you can ask Claude to:

1. Learn about Channlize:

   • "What is Channlize and how does it work?"
   • "Show me how to integrate a contact form"
   • "What's the structure of a chat session?"

2. Submit forms:

   • "Submit a contact form with name 'John Doe', email '[email protected]', and message 'Need help with billing'"

3. Manage chat sessions:

   • "Create a new chat session"
   • "Send a message 'Hello!' to session session_123"
   • "Get messages from session session_123"

4. Get integration help:

   • "Show me how to add a contact form to my Next.js app with Tailwind CSS"
   • "How do I set up webhooks for Channlize?"

API Reference

ChannlizeMCPServer

Main server class for creating MCP servers.

class ChannlizeMCPServer {
  constructor(options?: MCPServerOptions);
  
  setConfig(config: ChannlizeMCPConfig): void;
  getServer(): Server;
  runStdio(): Promise<void>;
  close(): Promise<void>;
}

Types

interface ChannlizeMCPConfig {
  apiKey: string;
  projectId?: string;
  baseUrl?: string;
  timeout?: number;
}

interface MCPServerOptions {
  name?: string;
  version?: string;
  config?: ChannlizeMCPConfig;
}

Helper Functions

// Resources
function listResources(): Resource[];
function getResource(uri: string): Resource | undefined;

// Tools
function listTools(): ToolDefinition[];
function getTool(name: string): ToolDefinition | undefined;

// Prompts
function listPrompts(): PromptDefinition[];
function getPrompt(name: string): PromptDefinition | undefined;

// Factory
function createMCPServer(options?: MCPServerOptions): ChannlizeMCPServer;

Custom Integrations

You can build custom MCP integrations using the library:

import { createMCPServer, listTools, listResources } from '@channlize/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

// Create server with your config
const server = createMCPServer({
  config: {
    apiKey: process.env.CHANNLIZE_API_KEY!,
    projectId: process.env.CHANNLIZE_PROJECT_ID,
  },
});

// Use custom transport (e.g., HTTP + SSE)
const transport = new SSEServerTransport('/mcp', response);
await server.getServer().connect(transport);

// List available capabilities
console.log('Resources:', listResources().map(r => r.uri));
console.log('Tools:', listTools().map(t => t.name));

Security

• API keys are required for all tool operations
• Keys are never exposed in resource responses
• Webhook signature verification recommended for production
• Use environment variables for sensitive credentials

Error Handling

The server handles and reports errors gracefully:

try {
  await client.submitContactForm(data);
} catch (error) {
  // Error details returned to MCP client
  console.error({
    success: false,
    error: error.message,
    code: error.code,
    statusCode: error.statusCode,
  });
}

Requirements

• Node.js 18+
• Valid Channlize API key (widget key)
• Active Channlize project

Related Packages

• @channlize/core - Core TypeScript SDK
• @channlize/react - React components and hooks

Contributing

See the main SDK repository for contribution guidelines.

License

MIT - see LICENSE file for details.

Support

• Documentation: https://docs.channlize.com
• GitHub Issues: https://github.com/channlize/sdk/issues
• Email: [email protected]

Changelog

0.1.0 (Initial Release)

• MCP server with stdio transport
• 5 resources (schemas + docs)
• 5 tools (form submission, chat management)
• 4 prompts (integration guides)
• Library and CLI support
• Full TypeScript support