What can you do with this 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 management * **MCP 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

Which integrations are available for this server?

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](/mcp/servers/integrations/pix) instant payment options for Brazilian e-commerce checkout processes.

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 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

Prerequisites

Node.js 18+
Yarn package manager

Installation

Install dependencies:

yarn install

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

User sends a message to /api/chat
Chatbot 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 JSON
Chatbot 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.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

Customer Management & Payment Plans MCP Server & Chatbot

Features

MCP Server

AI Chatbot

Prerequisites

Installation

Usage

Running the MCP Server (standalone)

Running the AI Chatbot Server

Chatbot API Endpoints

POST /api/chat

POST /api/chat/reset

GET /health

MCP Tools

Tool 1: createCustomer

Required Parameters

Optional Parameters

Example Request

Example Success Response

Example Error Response

Tool 2: getAddressByZipcode

Required Parameters

Example Request

Example Success Response

Tool 3: list_payment_plans

Required Parameters

Configuration (Environment Variables)

Example Response

Notes

Example Error Response

Configuring with MCP Clients

How the Chatbot Works

Example Chatbot Conversations

Project Structure

API Endpoint

Development Logging

Error Handling

Security

License

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API