MCP Server

Tomba MCP Tools

MCP Tools

This document provides detailed information about all nine tools available in the Tomba MCP Server. Each tool offers specific email intelligence capabilities with comprehensive input validation and structured output.

Tools Overview

Tool	Purpose	Input	Output Type
`domain_search`	Find emails by domain	Domain name + options	Email list with metadata
`email_finder`	Generate email from name + domain	First/last name + domain	Single email with confidence
`email_verifier`	Verify email deliverability	Email address	Verification status + score
`email_enrichment`	Enrich email with contact data	Email address	Complete contact profile
`author_finder`	Find author emails from articles	Article URL	Author contact list
`linkedin_finder`	Find emails from LinkedIn	LinkedIn profile URL	Contact with verification
`phone_finder`	Find phone numbers	Email/domain/LinkedIn	Phone numbers with details
`phone_validator`	Validate phone numbers	Phone number	Validation results + carrier

Domain Search

Purpose: Discover all email addresses associated with a specific domain name.

Input Schema

Code
 
{
    "domain": "string (required)",
    "limit": "number (optional, default: 10)",
    "offset": "number (optional, default: 0)",
    "type": "string (optional: 'personal' | 'generic')",
    "sources": "boolean (optional, default: true)"
}

Parameters

Parameter	Type	Required	Description	Example
`domain`	string	Yes	Target domain name	`"github.com"`
`limit`	number	No	Max results to return (1-100)	`25`
`offset`	number	No	Results to skip for pagination	`0`
`type`	string	No	Filter by email type	`"personal"`
`sources`	boolean	No	Include source information	`true`

Example Usage

Code
 
// MCP Request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "domain_search",
        "arguments": {
            "domain": "github.com",
            "limit": 10,
            "type": "personal",
            "sources": true
        }
    }
}

Response Format

Code
 
{
    "domain": "github.com",
    "emails": [
        {
            "email": "john.doe@github.com",
            "first_name": "John",
            "last_name": "Doe",
            "position": "Senior Developer",
            "department": "Engineering",
            "type": "personal",
            "confidence": 95,
            "sources": [
                {
                    "uri": "https://github.com/about",
                    "website_piece": "team",
                    "extracted_on": "2024-01-15",
                    "last_seen_on": "2024-01-15",
                    "still_on_page": true
                }
            ]
        }
    ],
    "total": 147,
    "limit": 10,
    "offset": 0
}

Use Cases

Lead generation for sales teams
Competitive intelligence research
Contact discovery for partnerships
Email list building for marketing

Email Finder

Purpose: Generate the most likely email address for a person based on their name and company domain.

Input Schema

Code
 
{
    "domain": "string (required)",
    "firstName": "string (required)",
    "lastName": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
`domain`	string	Yes	Company domain	`"microsoft.com"`
`firstName`	string	Yes	Person's first name	`"Satya"`
`lastName`	string	Yes	Person's last name	`"Nadella"`

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "email_finder",
        "arguments": {
            "domain": "microsoft.com",
            "firstName": "Satya",
            "lastName": "Nadella"
        }
    }
}

Response Format

Code
 
{
    "email": "satya.nadella@microsoft.com",
    "score": 98,
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "gender": "male",
    "country": "US",
    "position": "CEO",
    "twitter": "@satyanadella",
    "linkedin": "https://linkedin.com/in/satya-nadella",
    "phone_number": null,
    "company": "Microsoft Corporation",
    "sources": [
        {
            "uri": "https://microsoft.com/leadership",
            "website_piece": "executive-team",
            "extracted_on": "2024-01-10",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}

Use Cases

Sales prospecting with known contacts
Recruiting specific individuals
Journalist source identification
Partnership outreach

Email Verifier

Purpose: Verify email address deliverability and check if it exists in Tomba's database.

Input Schema

Code
 
{
    "email": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
`email`	string	Yes	Email address to verify	`"test@example.com"`

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "email_verifier",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}

Response Format

Code
 
{
    "email": {
        "email": "satya.nadella@microsoft.com",
        "gibberish": false,
        "disposable": false,
        "webmail": false,
        "result": "deliverable",
        "score": 95
    },
    "sources": [
        {
            "uri": "https://microsoft.com/leadership",
            "website_piece": "executive-bio",
            "extracted_on": "2024-01-10",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}

Verification Results

Result	Description
`deliverable`	Email exists and can receive messages
`undeliverable`	Email doesn't exist or bounces
`risky`	Email exists but may have issues
`unknown`	Cannot determine deliverability

Use Cases

Email list cleaning before campaigns
Lead qualification and scoring
Contact database maintenance
Fraud prevention and validation

Email Enrichment

Purpose: Get comprehensive contact information and social profiles for an email address.

Input Schema

Code
 
{
    "email": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
`email`	string	Yes	Email to enrich	`"contact@company.com"`

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
        "name": "email_enrichment",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}

Response Format

Code
 
{
    "email": "satya.nadella@microsoft.com",
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "gender": "male",
    "country": "United States",
    "position": "Chief Executive Officer",
    "twitter": "satyanadella",
    "linkedin": "https://linkedin.com/in/satya-nadella",
    "phone_number": "+1-425-882-8080",
    "company": "Microsoft Corporation",
    "industry": "Technology",
    "website": "microsoft.com"
}

Use Cases

CRM data enrichment
Lead scoring and qualification
Personalized outreach preparation
Contact profile completion

Author Finder

Purpose: Extract email addresses of authors from article URLs.

Input Schema

Code
 
{
    "url": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
`url`	string	Yes	Article or blog post URL	`"https://example.com/article"`

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
        "name": "author_finder",
        "arguments": {
            "url": "https://github.blog/2024-01-15-new-features/"
        }
    }
}

Response Format

Code
 
{
    "emails": [
        {
            "email": "author@github.com",
            "first_name": "Jane",
            "last_name": "Smith",
            "position": "Technical Writer",
            "twitter": "janesmith_dev",
            "linkedin": "https://linkedin.com/in/janesmith"
        },
        {
            "email": "editor@github.com",
            "first_name": "Mike",
            "last_name": "Johnson",
            "position": "Content Editor",
            "twitter": "mikejohnson",
            "linkedin": "https://linkedin.com/in/mikejohnson"
        }
    ]
}

Use Cases

Journalist contact discovery
Guest posting outreach
Expert source identification
Content collaboration

LinkedIn Finder

Purpose: Find email addresses associated with LinkedIn profile URLs.

Input Schema

Code
 
{
    "url": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
`url`	string	Yes	LinkedIn profile URL	`"https://linkedin.com/in/username"`

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
        "name": "linkedin_finder",
        "arguments": {
            "url": "https://linkedin.com/in/satya-nadella"
        }
    }
}

Response Format

Code
 
{
    "email": "satya.nadella@microsoft.com",
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "country": "United States",
    "gender": "male",
    "position": "Chief Executive Officer",
    "twitter": "satyanadella",
    "phone_number": null,
    "company": "Microsoft",
    "verification": {
        "date": "2024-01-15",
        "signature": "verified_profile_abc123"
    }
}

Use Cases

Sales prospecting from LinkedIn
Recruiting pipeline development
Professional networking
Contact verification from social profiles

Use Cases

Market research and analysis
Competitive intelligence gathering
Partnership opportunity identification
Industry mapping and analysis

Phone Finder

Purpose: Search for phone numbers based on email address, domain, or LinkedIn profile.

Input Schema

Code
 
{
    "email": "string (optional)",
    "domain": "string (optional)",
    "linkedin": "string (optional)"
}

Note: At least one parameter is required.

Parameters

Parameter	Type	Required	Description	Example
`email`	string	No*	Email address	`"contact@company.com"`
`domain`	string	No*	Company domain	`"company.com"`
`linkedin`	string	No*	LinkedIn profile URL	`"https://linkedin.com/in/user"`

*At least one parameter is required.

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
        "name": "phone_finder",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}

Response Format

Code
 
{
    "phone_number": "+1-425-882-8080",
    "country": "United States",
    "local_format": "(425) 882-8080",
    "intl_format": "+1 425 882 8080",
    "carrier": "Verizon",
    "line_type": "landline"
}

Use Cases

Multi-channel contact strategies
Lead enrichment with phone data
Customer service contact verification
Sales outreach diversification

Phone Validator

Purpose: Validate phone numbers and retrieve carrier information.

Input Schema

Code
 
{
    "phone": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
`phone`	string	Yes	Phone number to validate	`"+1-425-882-8080"`

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
        "name": "phone_validator",
        "arguments": {
            "phone": "+14258828080"
        }
    }
}

Response Format

Code
 
{
    "phone_number": "+14258828080",
    "valid": true,
    "country": "United States",
    "country_code": "US",
    "local_format": "(425) 882-8080",
    "intl_format": "+1 425 882 8080",
    "carrier": "Verizon Business",
    "line_type": "landline",
    "is_mobile": false
}

Validation Results

Field	Description
`valid`	Whether the phone number is valid
`country`	Country name
`country_code`	ISO country code
`local_format`	Local formatting
`intl_format`	International formatting
`carrier`	Telecom carrier name
`line_type`	"mobile", "landline", or "voip"
`is_mobile`	Boolean indicating mobile number

Use Cases

Contact data validation
SMS campaign preparation
Fraud prevention
Call routing optimization

Common Parameters

Pagination

Many tools support pagination through limit and offset:

Code
 
{
    "limit": 25, // Items per page (max: 100)
    "offset": 50 // Items to skip (for page 3 with limit 25)
}

Confidence Scoring

Results include confidence scores (0-100):

90-100: Very High - Verified or highly likely
70-89: High - Strong indicators
50-69: Medium - Some evidence
30-49: Low - Weak indicators
0-29: Very Low - Speculative

Source Attribution

Many results include source information:

Code
 
{
    "sources": [
        {
            "uri": "https://example.com/page",
            "website_piece": "contact",
            "extracted_on": "2024-01-15",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}

Error Handling

All tools return consistent error formats:

Code
 
{
    "content": [
        {
            "type": "text",
            "text": "Error: Invalid email format provided"
        }
    ],
    "isError": true
}

Common Error Types

Invalid Input: Malformed parameters
Rate Limit: API quota exceeded
Authentication: Invalid API credentials
Not Found: No results for query
Network Error: Connection issues

Usage Tips

Best Practices

Start Small: Use small limits while testing
Verify Inputs: Validate parameters before sending
Handle Errors: Always check for error responses
Rate Limiting: Respect API limits and implement backoff
Data Quality: Use confidence scores for filtering

Performance Optimization

Use pagination for large result sets
Batch similar requests when possible
Cache results when appropriate
Monitor API quota usage

Data Privacy

Only request necessary data
Handle personal information securely
Respect opt-out requests
Follow local privacy regulations

Ready to use these tools? Check out the LLM Integration Guide for connecting with AI applications.

Last modified on September 24, 2025

MCP Server - Introduction Tomba MCP LLM Integration