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
-
Open Claude Desktop settings
-
Navigate to the MCP configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add the LeadsDB server configuration:
Code
-
Restart Claude Desktop
-
When you first use LeadsDB tools, Claude will prompt you to authenticate. Enter your API key from the Settings page.
Cursor IDE
-
Open Cursor settings (
Cmd/Ctrl + ,) -
Search for "MCP" in settings
-
Add a new MCP server with:
- Name:
leadsdb - URL:
https://getleadsdb.com/mcp/sse
- Name:
-
When prompted, authenticate with your API key
Other MCP Clients
For any MCP-compatible client, use the following SSE endpoint:
Code
Authentication
LeadsDB MCP uses OAuth 2.0 with PKCE for secure authentication. The flow works as follows:
- MCP client discovers OAuth endpoints via
/.well-known/oauth-authorization-server - Client registers dynamically via
/register(RFC 7591) - User authenticates with their API key at
/authorize - Client exchanges authorization code for access token at
/token - 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
- Verify the MCP endpoint URL:
https://getleadsdb.com/mcp/sse - Check that your API key is valid
- Ensure your network allows SSE connections
Tools not appearing
- Restart your MCP client after configuration changes
- Verify the configuration JSON syntax is correct
- Check the client's MCP logs for errors