MCP Setup Guide

Copy page

MCP (Model Context Protocol) Setup Guide

LeadsDB supports the Model Context Protocol (MCP), allowing you to connect AI assistants like Claude, Cursor, and other MCP-compatible clients directly to your leads database.

What is MCP?

MCP is an open protocol that enables AI assistants to securely access external data sources and tools. With LeadsDB's MCP integration, you can:

• Search and filter leads using natural language
• Create, update, and delete leads through AI conversations
• Export leads to CSV or JSON
• Add notes and tags to leads
• Get statistics and insights about your leads

Available MCP Tools

LeadsDB exposes the following tools to MCP clients:

Tool	Description
search_leads	Search leads with filters (category, city, rating, etc.)
get_lead	Get detailed information about a specific lead
create_lead	Create a new lead
update_lead	Update an existing lead
delete_lead	Delete a lead
get_stats	Get dashboard statistics
get_categories	Get top categories
get_cities	Get top cities
export_leads	Export leads to CSV or JSON
add_tag	Add a tag to multiple leads
add_note	Add a note to a lead
get_notes	Get notes for a lead
delete_note	Delete a note

Setup Instructions

Claude Desktop

1. Open Claude Desktop settings

2. Navigate to the MCP configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add the LeadsDB server configuration:

Code
 
{
  "mcpServers": {
    "leadsdb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://getleadsdb.com/mcp/sse"],
      "env": {}
    }
  }
}

4. Restart Claude Desktop

5. When you first use LeadsDB tools, Claude will prompt you to authenticate. Enter your API key from the Settings page.

Cursor IDE

1. Open Cursor settings (Cmd/Ctrl + ,)

2. Search for "MCP" in settings

3. Add a new MCP server with:

   • Name: leadsdb
   • URL: https://getleadsdb.com/mcp/sse

4. When prompted, authenticate with your API key

Other MCP Clients

For any MCP-compatible client, use the following SSE endpoint:

Code
 
https://getleadsdb.com/mcp/sse

Authentication

LeadsDB MCP uses OAuth 2.0 with PKCE for secure authentication. The flow works as follows:

1. MCP client discovers OAuth endpoints via /.well-known/oauth-authorization-server
2. Client registers dynamically via /register (RFC 7591)
3. User authenticates with their API key at /authorize
4. Client exchanges authorization code for access token at /token
5. Access token is used for subsequent MCP requests

OAuth Endpoints

Endpoint	Description
GET /.well-known/oauth-authorization-server	OAuth metadata discovery
POST /register	Dynamic client registration
GET/POST /authorize	User authorization
POST /token	Token exchange

Token Lifetimes

• Access Token: 1 hour
• Refresh Token: 30 days

Example Conversations

Once connected, you can interact with your leads using natural language:

Searching Leads

"Find all restaurants in Athens with a rating above 4"

"Show me leads that have an email but no phone number"

"List the top 10 leads by review count in the Technology category"

Creating Leads

"Create a new lead for 'Acme Corp' - they're a software company in San Francisco, website is acme.com"

Managing Leads

"Add the tag 'priority' to leads in New York with rating above 4.5"

"Add a note to lead_xxx: 'Scheduled demo for next week'"

Analytics

"What are my top 5 categories by lead count?"

"How many leads have email addresses?"

Tool Parameters

search_leads

Parameter	Type	Description
category	string	Filter by category
city	string	Filter by city
state	string	Filter by state
country	string	Filter by country
tag	string	Filter by tag
name	string	Search by name (prefix match)
has_email	boolean	Only leads with email
has_phone	boolean	Only leads with phone
has_website	boolean	Only leads with website
min_rating	number	Minimum rating
limit	integer	Max results (default: 20, max: 100)
cursor	string	Pagination cursor

create_lead

Parameter	Type	Required	Description
name	string	Yes	Lead name
source	string	Yes	Lead source
description	string	No	Description
category	string	No	Category
address	string	No	Street address
city	string	No	City
state	string	No	State/Province
country	string	No	Country
postal_code	string	No	Postal code
phone	string	No	Phone number
email	string	No	Email address
website	string	No	Website URL
rating	number	No	Rating (0-5)
review_count	integer	No	Review count
tags	string	No	Comma-separated tags

update_lead

Parameter	Type	Required	Description
id	string	Yes	Lead ID
name	string	No	New name
description	string	No	New description
(other fields)	-	No	Same as create_lead

export_leads

Parameter	Type	Required	Description
format	string	Yes	csv or json
category	string	No	Filter by category
city	string	No	Filter by city
country	string	No	Filter by country
tag	string	No	Filter by tag
has_email	boolean	No	Only leads with email
has_phone	boolean	No	Only leads with phone
has_website	boolean	No	Only leads with website
min_rating	number	No	Minimum rating
limit	integer	No	Max results (default: 100, max: 1000)

Rate Limits

MCP requests count toward your API rate limits:

Plan	Limit	Window
Free	100 requests	10 minutes
Pro	1,000 requests	10 minutes

Troubleshooting

"Authentication required" error

Make sure you've entered your API key when prompted. You can find your API key on the Settings page.

"Rate limit exceeded" error

Wait a few minutes before making more requests, or upgrade to the Pro plan for higher limits.

Connection issues

1. Verify the MCP endpoint URL: https://getleadsdb.com/mcp/sse
2. Check that your API key is valid
3. Ensure your network allows SSE connections

Tools not appearing

1. Restart your MCP client after configuration changes
2. Verify the configuration JSON syntax is correct
3. Check the client's MCP logs for errors

Resources

• Model Context Protocol Specification
• Claude Desktop MCP Documentation
• MCP Remote Package