Customer Registration MCP Server

A Model Context Protocol (MCP) server for creating customers via an external API with Bearer token authentication.

Features

• ✅ MCP-compliant server implementation

• ✅ Bearer token authentication

• ✅ Required field validation (name, email, phone)

• ✅ Support for all optional customer fields

• ✅ Comprehensive error handling

• ✅ Development logging

• ✅ TypeScript implementation

Prerequisites

• Node.js 18+

• Yarn package manager

Installation

1. Install dependencies:

2. Configure environment variables:

Create a .env file in the root directory:

Usage

Development Mode

Run the server with auto-reload:

Or with watch mode:

Production Mode

1. Build the project:

2. Run the compiled server:

MCP Tool: createCustomer

Required Parameters

• name (string): Customer full name

• email (string): Customer email address (validated)

• phone (string): Customer phone number

Optional Parameters

• retention (boolean): Retention flag

• identification (string): Customer ID document (e.g., CPF)

• zipcode (string): ZIP/Postal code

• state (string): State/Province

• street (string): Street name

• number (string): Street number

• neighborhood (string): Neighborhood

• city (string): City

• list_ids (number): List ID for categorization

• create_deal (boolean): Whether to create a deal

• tags (string): Tags for the customer

• url (string): URL reference

• utm_term (string): UTM term parameter

• utm_medium (string): UTM medium parameter

• utm_source (string): UTM source parameter

• utm_campaign (string): UTM campaign parameter

• company_id (string): Company ID

• utm_content (string): UTM content parameter

Example Request

Example Success Response

Example Error Response

Configuring with MCP Clients

To use this server with an MCP-compatible client (like Claude Desktop), add the following to your MCP settings configuration:

Project Structure

API Endpoint

POST https://{{host}}/api/v1/customers

Headers:

• Authorization: Bearer {{TOKEN}}

• Content-Type: application/json

Development Logging

When NODE_ENV=development, the server logs:

• Request URLs and payloads

• Response status and data

• API errors with details

Error Handling

The server handles:

• Missing or invalid required fields

• HTTP errors from the external API

• Network connectivity issues

• Invalid Bearer tokens

• Malformed requests

Security

• Environment variables are used for sensitive data (API host and token)

• .env files are gitignored

• Bearer token is never logged or exposed

• Email validation prevents basic injection attempts

License

MIT