Skip to main content
Glama
Customer Registration MCP Server

Customer Registration MCP Server

by rodrigoai

Customer Management & Payment Plans MCP Server & Chatbot

This project provides two main components:

  1. MCP Server: A Model Context Protocol server for customer management, address lookup, and payment plan retrieval

  2. AI Chatbot: An OpenAI GPT-4o-mini powered chatbot that integrates with the MCP server via REST API

Features

MCP Server

  • ✅ MCP-compliant server implementation (stdio transport)

  • ✅ Bearer token authentication

  • ✅ Three integrated tools:

    • createCustomer - Customer registration with validation

    • getAddressByZipcode - Brazilian CEP address lookup

    • list_payment_plans - Payment plan retrieval (credit card, PIX, bank slip)

  • ✅ Required field validation

  • ✅ Comprehensive error handling

  • ✅ Development logging

  • ✅ TypeScript implementation

AI Chatbot

  • ✅ OpenAI GPT-4o-mini integration

  • ✅ Configurable tone/style via environment variables

  • ✅ REST API endpoint (/api/chat)

  • ✅ Automatic MCP tool invocation based on conversation

  • ✅ Conversation history management

  • ✅ Express-based HTTP server

Related MCP server: SRP Hub MCP

Prerequisites

  • Node.js 18+

  • Yarn package manager

Installation

  1. Install dependencies:

yarn install
  1. Configure environment variables:

Copy the example file and edit with your values:

cp .env.example .env

Edit .env:

# MCP Server Configuration
CUSTOMER_API_HOST=https://your-api-host.com
CUSTOMER_API_TOKEN=your_bearer_token_here
NODE_ENV=development

# Payment Plans Configuration
CHECKOUT_ID=your_checkout_id_here
PRODUCT_ID=36,42

# Chatbot Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-5-nano
AGENT_TONE=Professional, helpful, and efficient
# Alternative: AGENT_STYLE=Encouraging, visionary, witty

# Chatbot Server Port (optional, defaults to 3000)
CHATBOT_PORT=3000

Note: AGENT_TONE or AGENT_STYLE controls the chatbot's personality.

Usage

Running the MCP Server (standalone)

Development Mode:

yarn dev

Or with watch mode:

yarn watch

Production Mode:

# Build
yarn build

# Run
yarn start

Running the AI Chatbot Server

Development Mode:

yarn chatbot:dev

Production Mode:

# Build
yarn chatbot:build

# Run
yarn chatbot:start

The chatbot server will start on port 3000 (or your configured CHATBOT_PORT).

Chatbot API Endpoints

POST /api/chat

Send a message to the chatbot:

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Register a customer: John Doe, john@example.com, +1234567890",
    "context": {}
  }'

Response:

{
  "reply": "Great! I've successfully registered John Doe as a customer. The customer ID is 12345.",
  "actions": [
    {
      "tool": "createCustomer",
      "input": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
      },
      "result": {
        "status": "success",
        "customerId": 12345,
        "data": {...}
      }
    }
  ]
}

POST /api/chat/reset

Reset the conversation history:

curl -X POST http://localhost:3000/api/chat/reset

GET /health

Health check:

curl http://localhost:3000/health

MCP Tools

Tool 1: 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

{
  "name": "Tony Stark",
  "email": "newone@avengers.com",
  "phone": "(12) 99756-0001",
  "city": "São Paulo",
  "retention": true,
  "identification": "251.482.720-58",
  "tags": "coyo-jan"
}

Example Success Response

{
  "status": "success",
  "customerId": 12345,
  "data": {
    "id": 12345,
    "name": "Tony Stark",
    "email": "newone@avengers.com",
    ...
  }
}

Example Error Response

{
  "status": "error",
  "error": "Validation failed",
  "errors": [
    "email is required",
    "phone is required"
  ]
}

Tool 2: getAddressByZipcode

Lookup Brazilian addresses by CEP (zipcode).

Required Parameters

  • zipcode (string): Brazilian CEP in format XXXXX-XXX or XXXXXXXX (8 digits)

Example Request

{
  "zipcode": "01310-100"
}

Example Success Response

{
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "bairro": "Bela Vista",
  "localidade": "São Paulo",
  "uf": "SP"
}

Tool 3: list_payment_plans

Retrieve available payment plans for checkout offers. Configuration is read from environment variables (CHECKOUT_ID and PRODUCT_ID).

Required Parameters

None - the tool uses configuration from environment variables.

Configuration (Environment Variables)

  • CHECKOUT_ID (string): Checkout page identifier

  • PRODUCT_ID (string): Comma-separated product IDs (e.g., "36,42")

Example Response

{
  "checkout_id": "checkout_abc123",
  "product_id": "36,42",
  "plans": {
    "credit_card": [
      { "installments": 1, "value": 1096.00 },
      { "installments": 2, "value": 548.00 },
      { "installments": 3, "value": 365.33 },
      { "installments": 6, "value": 182.67 },
      { "installments": 12, "value": 91.33 }
    ],
    "pix": [
      { "value": 1096.00 }
    ],
    "bank_slip": [
      { "value": 1096.00 }
    ]
  },
  "payment_summary": "Temos pagamentos em até 12x de R$ 91,33 no cartão de crédito, ou à vista no PIX por R$ 1.096,00 ou boleto por R$ 1.096,00."
}

Notes

  • The API is called once with the full product_id string (comma-separated)

  • Backend processes multiple product IDs and returns combined payment conditions

  • Fine, fine_tax, and late_interest fields are automatically ignored

  • Payment summary is generated in Portuguese (Brazil)

Example Error Response

{
  "error": "Request failed with status code 401",
  "statusCode": 401
}

Configuring with MCP Clients

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

{
  "mcpServers": {
    "customer-registration": {
      "command": "node",
      "args": ["/absolute/path/to/mcpNova/build/index.js"],
      "env": {
        "CUSTOMER_API_HOST": "https://your-api-host.com",
        "CUSTOMER_API_TOKEN": "your_bearer_token_here",
        "NODE_ENV": "production",
        "CHECKOUT_ID": "your_checkout_id",
        "PRODUCT_ID": "36,42"
      }
    }
  }
}

How the Chatbot Works

  1. User sends a message to /api/chat

  2. Chatbot adds message to conversation history

  3. OpenAI GPT-4o-mini processes the message with configured system prompt

  4. If LLM determines an action is needed (e.g., createCustomer, getAddressByZipcode, list_payment_plans), it responds with JSON

  5. Chatbot extracts the action and calls MCP server via stdio

  6. MCP server executes the appropriate tool:

    • Customer registration via external API

    • Address lookup via ViaCEP

    • Payment plans retrieval via external API

  7. Result is returned to LLM for a friendly follow-up message in Portuguese

  8. Final response sent back to user

Example Chatbot Conversations

Customer Registration:

User: Preciso cadastrar um cliente: João Silva, joao@email.com, (11) 98765-4321

Chatbot: Perfeito! Cadastrei o João Silva com sucesso. O ID do cliente é 67890.

Address Lookup:

User: Qual endereço do CEP 01310-100?

Chatbot: `O CEP 01310-100 corresponde a:

  • Avenida Paulista

  • Bairro: Bela Vista

  • São Paulo - SP`

Payment Plans:

User: Quais são as formas de pagamento?

Chatbot: `Temos as seguintes opções:

  • Cartão de crédito: até 12x de R$ 91,33

  • PIX à vista: R$ 1.096,00

  • Boleto à vista: R$ 1.096,00`

Multi-turn with Address:

User: Quero cadastrar um cliente

Chatbot: `Claro! Preciso de:

  • Nome completo

  • E-mail

  • Telefone`

User: Nome: Maria Santos, Email: maria@email.com, Telefone: (21) 99999-8888, CEP: 20040-020

Chatbot: (looks up CEP) Encontrei o endereço: Avenida Rio Branco, Centro, Rio de Janeiro - RJ. Vou cadastrar a Maria Santos com essas informações.

(creates customer)

Chatbot: Pronto! Maria Santos cadastrada com sucesso. ID: 11223

Project Structure

mcpNova/
├── src/
│   ├── index.ts                  # MCP Server (stdio)
│   ├── chatbotServer.ts          # Express REST API server
│   └── services/
│       ├── customerService.ts    # Customer API integration
│       ├── viaCepService.ts      # Brazilian address lookup
│       ├── paymentPlansService.ts # Payment plans retrieval
│       ├── mcpClient.ts          # MCP client (stdio communication)
│       └── chatbotService.ts     # OpenAI integration & logic
├── build/                        # Compiled TypeScript
├── package.json
├── tsconfig.json
├── .env                          # Environment variables (gitignored)
├── .env.example                  # Environment template
└── README.md

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

Available Tools

1 tool
createCustomerC

Create a new customer in the external API. Requires name, email, and phone. Supports optional fields like address, UTM parameters, and more.

Inputs: name (required), email (required), phone (required), retention, +17 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion or overlap between tools. The tool has a clear and distinct purpose: creating a new customer.

    Naming Consistency5/5

    The single tool name 'createCustomer' uses a consistent verb_noun pattern (create + Customer). Since there is only one tool, naming consistency is inherently perfect.

    Tool Count2/5

    A single tool for a 'Customer Registration' server is too few for the apparent scope. Registration typically involves more operations like retrieving, updating, or deleting customer data, making this server feel incomplete and under-scoped.

    Completeness2/5

    The server is severely incomplete for customer registration. It only provides a create operation, lacking essential tools for reading, updating, or deleting customers, which are fundamental for any registration system. This will likely cause agent failures when trying to manage customer data.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with GoHighLevel's complete API including contacts, opportunities, calendars, workflows, communications, and business management tools. Supports both Bearer token and OAuth2 authentication with automatic token management.
      22 npm
      10
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connects AI assistants to the Hub API, enabling them to manage resources such as customer leads through structured tools. It provides validated operations for creating customer records, supporting specific Brazilian fiscal ID (CPF/CNPJ) validation rules.
      1
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to manage contacts through CRUD operations (list, get, create/upsert by email, update, delete) with OAuth 2.1 authentication.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to manage omnichannel CRM data (WhatsApp, Instagram, Facebook) via the official API, including leads, deals, pipelines, activities, tags, products, conversations, lists, attachments, and notes.
      MIT