Local MCP Server - Introduction

What is the Tomba MCP Server?

The Tomba MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Tomba.io's powerful email discovery and verification APIs. It allows Large Language Models (LLMs) and AI applications to access comprehensive email intelligence capabilities through a standardized protocol.

Purpose & Benefits

For AI Applications

• Structured Access: Provides LLMs with reliable, structured access to email data
• Real-time Intelligence: Get up-to-date email verification and discovery results
• Scalable Integration: Handle multiple concurrent requests with proper error handling
• Protocol Standardization: Uses MCP for consistent tool interfaces across different AI systems

For Developers

• Easy Integration: Simple JSON-RPC interface for any MCP-compatible client
• Type Safety: Full TypeScript implementation with comprehensive type definitions
• Comprehensive Testing: Extensive test suite and debugging tools
• Professional Grade: Production-ready with proper error handling and logging

Architecture Overview

Code
 
graph TD
    A[AI Assistant/LLM] --> B[MCP Client]
    B --> C[Tomba MCP Server]
    C --> D[Tomba.io API]

    C --> E[Domain Search]
    C --> F[Email Verification]
    C --> G[Contact Enrichment]
    C --> H[Phone Discovery]

    subgraph "MCP Server Tools"
        E
        F
        G
        H
    end

Components

1. MCP Server Core: Handles protocol communication and request routing
2. Tomba Client Wrapper: Abstracts Tomba.io SDK with error handling
3. Tool Registry: Nine specialized tools for different email intelligence tasks
4. Type System: Complete TypeScript definitions for all data structures

Core Capabilities

Email Discovery

• Domain Search: Find all emails associated with any domain
• Email Finder: Generate likely email addresses from names + domain
• Author Finder: Extract author emails from article URLs
• LinkedIn Finder: Discover emails from LinkedIn profile URLs

Email Intelligence

• Email Verifier: Check deliverability and validate email addresses
• Email Enrichment: Get comprehensive contact information
• Company Discovery: Find relevant companies and their contact data

Phone Intelligence

• Phone Finder: Search phone numbers by email, domain, or LinkedIn
• Phone Validator: Validate phone numbers and get carrier information

Model Context Protocol (MCP)

What is MCP?

The Model Context Protocol is an open standard that enables secure connections between AI applications and external data sources. It provides:

• Standardized Communication: Consistent JSON-RPC based protocol
• Security: Controlled access to external APIs and data
• Flexibility: Works with any MCP-compatible LLM or AI application
• Extensibility: Easy to add new tools and capabilities

Why MCP for Email Intelligence?

• Real-time Data: Access live email verification and discovery data
• Structured Responses: Consistent data formats for reliable AI processing
• Error Handling: Graceful handling of API limits and errors
• Scalability: Handle multiple concurrent requests efficiently

Use Cases

For Sales & Marketing

• Lead Generation: Find contact information for prospects
• Email Validation: Verify email lists before campaigns
• Contact Enrichment: Enhance existing contact databases
• Competitive Intelligence: Research competitor contact information

For Recruitment

• Candidate Research: Find contact information for potential hires
• Company Intelligence: Research target organizations
• Contact Verification: Validate candidate-provided information

For Research & Journalism

• Source Discovery: Find expert contacts in specific industries
• Fact Checking: Verify contact information and company details
• Interview Sourcing: Locate article authors and subject matter experts

For Data Quality

• Database Cleaning: Validate and enrich existing contact data
• Duplicate Detection: Identify and merge duplicate contact records
• Information Verification: Cross-reference contact details across sources

🔧 Technical Specifications

Supported Protocols

• MCP Version: 2024-11-05
• Transport: stdio (standard input/output)
• Message Format: JSON-RPC 2.0
• Authentication: API key + secret key

System Requirements

• Node.js: 16.0.0 or higher
• TypeScript: 5.2+ (for development)
• Memory: Minimum 512MB RAM
• Network: Internet connection for Tomba.io API access

API Rate Limits

• Respects Tomba.io rate limiting
• Handles 429 responses gracefully
• Implements exponential backoff for retries
• Provides clear error messages for limit exceeded

Quick Start Example

Here's how the MCP server integrates with an AI application:

Code
 
// AI requests available tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

// Server responds with tool definitions
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "domain_search",
        "description": "Search emails based on domain name",
        "inputSchema": {
          "type": "object",
          "properties": {
            "domain": {"type": "string"},
            "limit": {"type": "number"}
          }
        }
      }
    ]
  }
}

// AI calls a tool
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "domain_search",
    "arguments": {
      "domain": "github.com",
      "limit": 10
    }
  }
}

// Server returns results
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\n  \"emails\": [...],\n  \"total\": 25\n}"
    }]
  }
}

Data Quality & Reliability

Data Sources

• Tomba.io Database: 400+ million email addresses
• Real-time Verification: Live deliverability checking
• Multiple Sources: Web crawling, social networks, public databases
• Regular Updates: Continuously updated data sources

Accuracy Metrics

• Email Discovery: 95%+ accuracy for common domains
• Verification Results: Real-time SMTP validation
• Confidence Scores: Numerical confidence ratings for results
• Source Attribution: Full source tracking for discovered emails

Privacy & Compliance

• GDPR Compliant: Respects data protection regulations
• Opt-out Respect: Honors email opt-out requests
• No Storage: Server doesn't store or cache personal data
• Secure Transport: All communications over secure channels

Future Roadmap

Planned Features

• Webhook Support: Real-time notifications for data changes
• Bulk Operations: Batch processing for large datasets
• Custom Filtering: Advanced search and filtering capabilities
• Integration Templates: Pre-built integrations for popular platforms

Enhanced Intelligence

• AI-Powered Matching: Improved email pattern recognition
• Social Media Integration: Extended social profile discovery
• Company Insights: Enhanced company intelligence and metrics
• Predictive Scoring: ML-powered deliverability predictions

Next Steps

1. Tools Reference: Detailed documentation for each tool
2. LLM Integration: Connect with popular AI applications

Support & Resources

• GitHub Repository: tomba-mcp-server
• Tomba.io Documentation: developer.tomba.io
• MCP Specification: modelcontextprotocol.io
• Issue Tracker: Report bugs and request features on GitHub

The Tomba MCP Server bridges the gap between AI applications and professional email intelligence, enabling smarter, data-driven decisions in sales, marketing, recruitment, and research workflows.