Customer Registration MCP Server
This server provides customer management, Brazilian address lookup, and payment plan retrieval through an MCP-compliant interface with AI chatbot integration.
Core Capabilities:
Customer Registration - Create new customers with required fields (name, email, phone) and optional fields including address details, UTM tracking parameters, identification documents (e.g., CPF), retention flags, company IDs, categorization list IDs, tags, and URLs
Brazilian Address Lookup - Retrieve complete address information using CEP (Brazilian postal code) in formats XXXXX-XXX or XXXXXXXX via ViaCEP service, returning street, neighborhood, city, and state data
Payment Plan Retrieval - Query available payment options including credit card installments (1x to 12x), PIX, and bank slip (boleto) with automatic price calculations and Portuguese summaries
AI-Powered Chatbot - Interact via natural language through REST API endpoints (
/api/chat,/api/chat/reset,/health) powered by OpenAI GPT-4o-mini, supporting Portuguese and English with multi-turn conversation history managementMCP Protocol Compliance - Function as standard MCP server with stdio transport for integration with MCP-compatible clients like Claude Desktop, enabling direct tool access
Automated Validation - Enforce required fields, validate email formats, and handle error scenarios before API submission
Configurable Personality - Customize chatbot tone and style via environment variables (AGENT_TONE or AGENT_STYLE)
Deal Creation - Optionally trigger CRM deal creation during customer registration
Development Tools - Includes TypeScript implementation, logging, and both development and production modes
Powers an AI chatbot using GPT-4o-mini for natural language processing and automated tool invocation based on conversation context.
Retrieves payment plan information including PIX instant payment options for Brazilian e-commerce checkout processes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Customer Registration MCP Server register Tony Stark with email newone@avengers.com and phone (12) 99756-0001"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Customer Management & Payment Plans MCP Server & Chatbot
This project provides two main components:
MCP Server: A Model Context Protocol server for customer management, address lookup, and payment plan retrieval
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 validationgetAddressByZipcode- Brazilian CEP address lookuplist_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
Install dependencies:
yarn installConfigure environment variables:
Copy the example file and edit with your values:
cp .env.example .envEdit .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=3000Note: AGENT_TONE or AGENT_STYLE controls the chatbot's personality.
Usage
Running the MCP Server (standalone)
Development Mode:
yarn devOr with watch mode:
yarn watchProduction Mode:
# Build
yarn build
# Run
yarn startRunning the AI Chatbot Server
Development Mode:
yarn chatbot:devProduction Mode:
# Build
yarn chatbot:build
# Run
yarn chatbot:startThe 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/resetGET /health
Health check:
curl http://localhost:3000/healthMCP Tools
Tool 1: createCustomer
Required Parameters
name(string): Customer full nameemail(string): Customer email address (validated)phone(string): Customer phone number
Optional Parameters
retention(boolean): Retention flagidentification(string): Customer ID document (e.g., CPF)zipcode(string): ZIP/Postal codestate(string): State/Provincestreet(string): Street namenumber(string): Street numberneighborhood(string): Neighborhoodcity(string): Citylist_ids(number): List ID for categorizationcreate_deal(boolean): Whether to create a dealtags(string): Tags for the customerurl(string): URL referenceutm_term(string): UTM term parameterutm_medium(string): UTM medium parameterutm_source(string): UTM source parameterutm_campaign(string): UTM campaign parametercompany_id(string): Company IDutm_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 identifierPRODUCT_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_idstring (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
User sends a message to
/api/chatChatbot adds message to conversation history
OpenAI GPT-4o-mini processes the message with configured system prompt
If LLM determines an action is needed (e.g.,
createCustomer,getAddressByZipcode,list_payment_plans), it responds with JSONChatbot extracts the action and calls MCP server via stdio
MCP server executes the appropriate tool:
Customer registration via external API
Address lookup via ViaCEP
Payment plans retrieval via external API
Result is returned to LLM for a friendly follow-up message in Portuguese
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.mdAPI 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)
.envfiles are gitignoredBearer token is never logged or exposed
Email validation prevents basic injection attempts
License
MIT
Available Tools
1 toolcreateCustomerC
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
Scored across 1 tool
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.
The single tool name 'createCustomer' uses a consistent verb_noun pattern (create + Customer). Since there is only one tool, naming consistency is inherently perfect.
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.
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
Related MCP Connectors
Manage contacts, campaigns, senders, and deliverability via SuperSend API
Read SMS, WhatsApp, email, contacts and audiences from your Bird workspace, plus safe CRM writes.
CRM + visual automation builder AI agents can drive via MCP: contacts, tags, maps, email/SMS flows.
List and create Keap contacts, companies, tasks, opportunities, orders, tags and campaigns.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm10MIT
- AlicenseBqualityDmaintenanceConnects 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.11ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI clients to manage contacts through CRUD operations (list, get, create/upsert by email, update, delete) with OAuth 2.1 authentication.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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