BatchData MCP Demo

A reference implementation demonstrating secure server-side integration with the BatchData MCP Server using the Vercel AI SDK.

Features

• Multi-Provider LLM Support: Choose from OpenAI, Anthropic, or Google models
• Real-Time Progress Feedback: See live updates as AI tools are called via Server-Sent Events
• Secure Token Management: API tokens are kept server-side, never exposed to the browser
• Property Analysis: AI-powered investment analysis using BatchData property intelligence
• Skip Tracing: Find owner contact information with TCPA/DNC compliance filtering
• Property Comparison: Compare multiple properties for investment decisions
• Free Chat: General AI chat with access to all BatchData MCP tools

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Browser      │────▶│  Express.js     │────▶│ BatchData MCP   │
│   (Frontend)    │     │   Server        │     │    Server       │
│                 │     │                 │     │                 │
│  Model selector │     │ Tokens stored   │     │ Property data   │
│  No API tokens! │     │ in env vars     │     │ 140M+ records   │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
             ┌──────────┐ ┌──────────┐ ┌──────────┐
             │  OpenAI  │ │ Anthropic│ │  Google  │ ...
             │  GPT-4o  │ │  Claude  │ │  Gemini  │
             └──────────┘ └──────────┘ └──────────┘

Quick Start

1. Clone and Install

git clone https://github.com/CharlesParra-BatchService/BatchData-MCP-Demo.git
cd BatchData-MCP-Demo
npm install

2. Configure Environment

cp .env.example .env

Edit .env and add your API keys. At minimum, you need BatchData + one LLM provider:

# Required: BatchData API Token
BATCHDATA_API_TOKEN=bd-your-batchdata-token

# At least one LLM provider is required:
OPENAI_API_KEY=sk-your-openai-api-key
# ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
# GOOGLE_GENERATIVE_AI_API_KEY=your-google-api-key

Getting API Keys:

• BatchData: https://app.batchdata.com → API Tokens → Server Side Token
• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/settings/keys
• Google AI: https://aistudio.google.com/apikey
• Mistral: https://console.mistral.ai/api-keys/
• Groq: https://console.groq.com/keys

Note: Only models from providers with configured API keys will appear in the model selector.

3. Run the Server

Development (with hot reload):

npm run dev

Production:

npm run build
npm start

4. Open the Demo

Navigate to http://localhost:3000 in your browser.

API Endpoints

Endpoint	Method	Description
/api/models	GET	List available models
/api/ai/chat	POST	General chat with BatchData tools
/api/ai/chat-stream	POST	Chat with real-time progress (SSE)
/api/ai/analyze-property	POST	Property investment analysis
/api/ai/analyze-property-stream	POST	Analysis with progress (SSE)
/api/ai/skip-trace	POST	Owner contact lookup
/api/ai/skip-trace-stream	POST	Skip trace with progress (SSE)
/api/ai/compare-properties	POST	Compare multiple properties
/api/ai/compare-properties-stream	POST	Comparison with progress (SSE)
/api/health	GET	Health check

Example: Analyze Property

curl -X POST http://localhost:3000/api/ai/analyze-property \
  -H "Content-Type: application/json" \
  -d '{"address": "273 Woodbridge Ave, Woodbridge, NJ 07095"}'

Example: Chat

curl -X POST http://localhost:3000/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is the estimated value of 123 Main St, Phoenix, AZ 85001?"}
    ]
  }'

Security Best Practices

This demo demonstrates the correct way to integrate with BatchData and LLM providers:

1. Server-Side Tokens: All API tokens are stored in environment variables on the server
2. No Client Exposure: The browser never sees or handles API tokens
3. Proxy Pattern: Frontend calls your backend API, which then calls external services

Never do this:

// ❌ BAD - Token exposed in browser
const response = await fetch('https://mcp.batchdata.com', {
  headers: { Authorization: `Bearer ${apiToken}` }  // Visible to users!
});

Do this instead:

// ✅ GOOD - Token stays on server
const response = await fetch('/api/ai/analyze-property', {
  body: JSON.stringify({ address })  // No tokens sent from browser
});

Tech Stack

• Runtime: Node.js 18+
• Framework: Express.js
• AI Integration: Vercel AI SDK with generateText() and automatic tool execution
• MCP Client: @ai-sdk/mcp@^0.0.11 for BatchData MCP Server connection
• LLM Providers: OpenAI, Anthropic, Google (multi-provider support)
• Language: TypeScript

Known Issues

Token Limit Handling

BatchData MCP tools can return large amounts of data (50K+ characters for a single property lookup). This project includes automatic truncation of tool results to prevent exceeding LLM token limits.

Supported LLM Models

The demo includes a model selector dropdown. Available models depend on which API keys you configure:

Provider	Models	Env Variable
OpenAI	gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo	OPENAI_API_KEY
Anthropic	claude-sonnet-4-20250514, claude-3-5-haiku-20241022, claude-3-opus-20240229	ANTHROPIC_API_KEY
Google	gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash	GOOGLE_GENERATIVE_AI_API_KEY

The /api/models endpoint returns only models from providers with configured API keys. The frontend automatically populates the model selector based on this response.

Project Structure

BatchData-MCP-Demo/
├── src/
│   ├── ai-service.ts    # AI/MCP integration with Vercel AI SDK
│   └── server.ts        # Express.js server & routes
├── public/
│   └── index.html       # Frontend demo UI
├── docs/
│   └── AI-SDK-MCP-WORKAROUND.md  # Historical reference for beta versions
├── .env.example         # Environment template
├── package.json
├── tsconfig.json
└── README.md

Available BatchData MCP Tools

The AI has access to these BatchData tools:

Tool	Description
lookup_property	Get comprehensive property details
comparable_property	Find comparable properties for valuation
skip_trace_property	Find owner contact information
verify_phone	Verify phone numbers (carrier, DNC, TCPA)
check_dnc_status	Quick Do Not Call lookup
check_tcpa_status	Quick TCPA litigator check
verify_address	Normalize addresses to USPS standards
geocode_address	Convert address to coordinates
reverse_geocode_address	Convert coordinates to address

Resources

• BatchData MCP Server Developer Guide
• Vercel AI SDK Documentation
• MCP Protocol Specification

License

MIT