FindClients MCP
Connect FindClients to ChatGPT and Claude to count, price and buy lead lists with your FindClients credits.
FindClients MCP lets Claude and ChatGPT build, price and buy FindClients lead lists for you. The assistant uses your FindClients account and credits. The server uses the open Model Context Protocol and standard OAuth sign-in.
https://api.findclients.ai/mcpThe assistant can build lists of US businesses and contacts (B2B), consumer households (B2C), or properties and owners, with the List Builder filters. It can use industry playbooks, show samples and grow small lists. It can leave out records you bought or companies you name. It can deliver new records on a schedule and find prospects like your customers. It buys only after you say yes, within limits you set.
Before you start
- FindClients account: sign up free at findclients.ai, or during the first connection.
- AI app: Claude (claude.ai, Claude Desktop or Claude Code) or ChatGPT.
- Credits: buy credits or a plan on findclients.ai, not in the chat.
Connect an AI app
Let Claude Code connect it
Claude Code can connect FindClients for you. Copy this prompt and paste it into Claude Code. It adds the server and the FindClients prospecting skill, then tests the connection. You sign in on findclients.ai and approve (see Approve access).
Setup assistant that connects FindClients to this AI agent on my computer. FindClients builds and sells US prospect lists.
## Mission
Connect the FindClients MCP server and install the FindClients prospecting skill in this agent.
## Principles
- Use this agent's own remote MCP setup (HTTP) with OAuth sign-in. The server supports dynamic client registration.
- NEVER ask me for an API key or a password. NEVER install a local (stdio) package. I sign in on findclients.ai, not in this chat.
- Install for my user, so FindClients works in all my projects.
- Change ONLY this agent's settings.
## Workflow
1. Add the MCP server with the name findclients and the URL https://api.findclients.ai/mcp.
2. Download https://findclients.ai/skills/findclients-prospecting/SKILL.md into this agent's skills folder as findclients-prospecting/SKILL.md. If this agent has no skills, tell me and skip this step. The server gives the main rules itself.
3. Start the FindClients sign-in. A FindClients page opens in my browser, where I sign in and approve. If I must reload the agent or start the sign-in myself, give me the exact steps and wait for me.
4. Call findclients_get_wallet once to test the connection. It is free.
## Success Metrics
- The findclients server is connected and its tools are available.
- The findclients-prospecting skill is installed, or you told me why not.
- findclients_get_wallet returned my credit balance.
## Deliverable Template
Tell me what changed: the server, the skill, each file you changed, and my credit balance.To connect by hand, or to connect claude.ai, Claude Desktop or ChatGPT, do the steps below.
claude.ai and Claude Desktop
- Open Settings › Connectors and select Add custom connector.
- Type the name
FindClientsand paste the server URL above. - Select Connect. A FindClients page opens. Sign in and approve (see Approve access).
- In a chat, turn on FindClients in the tools menu and ask for a list.
On Team and Enterprise plans, an owner may need to add the connector for the organization first.
Claude Code
-
Run this command:
claude mcp add --transport http findclients https://api.findclients.ai/mcp -
Run
/mcpin Claude Code, selectfindclientsand select Authenticate. The sign-in page opens.
To use FindClients in every project, add --scope user to the command.
ChatGPT
FindClients is not in the ChatGPT app directory yet, so connect it in developer mode.
- Open Settings › Apps & Connectors › Advanced settings and turn on Developer mode.
- In Apps & Connectors, select Create.
- Type the name
FindClients, paste the server URL above and select OAuth for authentication. - Select Save. The FindClients sign-in page opens. Sign in and approve.
- In a new chat, add FindClients from the + menu and ask for a list.
Developer mode is available on paid ChatGPT plans. Workspace admins may need to allow it.
Approve access
The AI app sends you to findclients.ai. You sign in there, never in the chat. Then you approve the permissions, set two spending limits and go back to the app.
The approval page shows the app's name and the site that publishes it. If the app registered itself, the page says that the name is the app's own claim. The page also shows the site it returns you to. When a connected app asks again, the limits start from your earlier values. The page stays open for 30 minutes, so a new user can sign up first.
| Permission | Lets the app |
|---|---|
See the catalog (catalog:read) | See the filter catalog, count audiences (your lists too) and preview masked sample records |
Build lists (lists:write) | Build and change lists in your workspaces, also from your reports |
See your lists (lists:read) | See your workspaces, credit balance, schedules, purchased lists and their files |
Buy lists (lists:purchase) | Spend your credits on lists, schedules and report enrichments you confirm |
See your files (data:read) | See your files and the reports built from them |
Change your files (data:write) | Upload, combine and archive files, change, share or delete them once you confirm, and build reports from them |
Disconnect an app
Go to Account › Connected apps on findclients.ai and select Disconnect. The connection and all its tokens stop at once. A new connection needs a new approval. A password reset or change (also by an admin) and a deleted account disconnect every app.
Schedules belong to your FindClients account, so they continue after you disconnect the app. Pause or delete them under Auto Prospecting.
Credits and spending limits
Building, counting, samples, ways to grow a list and quotes are free. Only three actions spend credits: findclients_purchase_list, findclients_start_report and schedule runs.
- The assistant builds and counts the list. It can show samples and ways to grow it.
- It shows a quote: records, credits and your balance after. On business and consumer lists, FindClients never charges again for records you bought.
- You confirm in the chat. Only then does the assistant buy. Most AI apps also ask you to approve that call.
- The assistant gives you a download link. The file also stays on your Data Sources page.
FindClients tells every app to wait for your yes. FindClients itself enforces two limits per app:
| Limit | Default | When a purchase passes it |
|---|---|---|
| Most credits per purchase | 2,000 credits | FindClients refuses the purchase. Buy fewer records or raise the limit. |
| Most credits per day | 5,000 credits (UTC day) | FindClients refuses purchases until the next UTC day or until you raise it. |
To change the limits, go to Account › Connected apps › Edit limits. Use whole numbers from 0 to 1,000,000. A limit of 0 stops all purchases. New limits apply from the app's next request. Each app has its own daily total.
Schedules
- Schedules work for business and consumer lists, not property lists.
- A daily run starts at the hour you choose. Weekly and monthly runs start at 08:00, as in Auto Prospecting. A monthly run can be on the last day.
- When an app plans or resumes a schedule, one run can cost at most the per-purchase limit. So a limit of 0 also stops new and resumed schedules. Later limit changes do not change the schedule.
- Runs do not count toward the daily limit. FindClients skips a run when your balance is too low.
Watch the work in FindClients
The assistant saves every list in a workspace and gives you its link (workspace_url). Open it to see and finish the work on findclients.ai.
- Each change from the assistant appears with the changed fields highlighted and a note that names the app. Changes appear in about 2 seconds, or up to 10 seconds after a quiet period.
- Your unsaved edits stay, and the page tells you that the app changed the list or report. Save keeps your version. Show theirs loads the app's version.
- A list that you bought from, or that is in a purchase now, keeps its filters. New filters go into a new list with its own link. A change to only the columns or the name stays on the same list.
- A list built from a report can go into the workspace of that report.
- The link opens in the account that you connected, for example
d***@example.com. If your browser uses another account, select Sign in with another account to come back to the same link.
Find prospects like your customers
Give the assistant your customer list. FindClients learns who buys from you and finds more like them.
- The assistant finds the file in your Data Sources, or gives you a one-time upload link. Open the link in a browser where you are signed in to findclients.ai. Select a CSV or Excel file. When the page says File sent, tell the assistant. The link works for 30 minutes.
- The assistant starts a look-alike report and shows how it matched your columns (company, address, name). You can correct a column before anything runs.
- The assistant quotes the enrichment: the number of customers and the credits. Nothing is spent until you say yes.
- The assistant enriches your customers, then builds the report. You can watch both steps in the report's workspace.
- The assistant summarizes your best customers, answers questions about them and builds a prospect list like them. When you buy a business list built this way, FindClients leaves out the customers in your file.
File changes work the same way. The assistant shows the plan of an edit, a share or a delete. It applies the plan only after you confirm.
Example prompts
- "I sell solar panels. Find homeowners in Travis County, Texas who could buy, and show me a few examples."
- "Build a list of dentists in Orange County, California with 5 to 20 employees. Don't buy yet."
- "My list of HVAC contractors in Boise is small. How could I get more?"
- "Quote 500 restaurant owners in Miami, but leave out acme.com and bistro.com."
- "Send me 100 new homeowners in ZIP 92618 every Monday."
- "Show my recent FindClients lists and continue the one about law firms."
- "Here are my customers. Find me more businesses like them."
- "In my customer report, which ZIP codes have the most customers?"
Claude and Claude Code show these starter prompts, often as slash commands:
| Prompt | Asks you for |
|---|---|
find_customers | Who you sell to and where. The assistant picks the list type. |
business_prospects | An industry, a location and, if you want, a company size |
direct_mail_homeowners | An area and, if you want, property and owner criteria |
lookalike_from_customers | Your customer file. The assistant finds prospects like them. |
continue_list | A list in your workspaces to continue |
weekly_new_leads | A list and the number of new records you want each week |
Claude and Claude Code can also install the FindClients prospecting skill. It teaches the agent the best order of work: playbook, build, sample, widen, quote, and buy only after your yes.
Tools reference
All tool names start with findclients_, so they do not clash with tools from other servers.
| Tool | What it does | Permission | Calls per minute |
|---|---|---|---|
findclients_describe_catalog | Lists the filters and columns of one list type: b2b, b2c or property. | catalog:read | 60 |
findclients_get_industry_playbook | Returns an industry playbook: buyer filters, the must-keep qualifier and ways to widen. | catalog:read | 30 |
findclients_find_industries | Matches industry words to catalog industry codes. | catalog:read | 30 |
findclients_find_address | Finds a street address and its coordinates, to center a radius on it. | catalog:read | 30 |
findclients_list_workspaces | Lists your workspaces and their lists, newest first. With data_source_id, it lists only the workspaces that use that file. | lists:read | 30 |
findclients_get_list | Shows the list in a workspace: filters, columns, count and records bought. | lists:read | 60 |
findclients_recommend_columns | Ranks the columns worth adding to a business or consumer list. The build tool adds the columns you pick. | lists:read | 10 |
findclients_build_business_list | Creates or changes a business list and counts it. list_name renames a list. copy_from_workspace_id copies a list. | lists:write | 20 |
findclients_build_consumer_list | Creates or changes a consumer list and counts it. | lists:write | 20 |
findclients_build_property_list | Creates or changes a property list and counts it. | lists:write | 20 |
findclients_preview_sample | Shows up to 10 example records. Names show as initials and contact details stay hidden. | catalog:read | 20 |
findclients_suggest_broadening | Measures which filter changes grow a small list, each with its count and arguments. It can test only the filters you name, or wider bands of a consumer filter. | catalog:read | 6 |
findclients_suggest_linkedin_navigator_search | Builds a LinkedIn Sales Navigator search from the filters of a business list. | lists:read | 20 |
findclients_get_wallet | Shows your credit balance and plan. | lists:read | 60 |
findclients_quote_list | Prices a list: records, credits and balance after. It can leave out company domains, earlier purchases (all or chosen lists) and the customers of a report. | lists:purchase | 10 |
findclients_purchase_list | Buys a quote and returns an order_id. A retry of the same quote never charges twice. | lists:purchase | 5 |
findclients_get_order | Shows an order's status, records delivered, do-not-contact records removed and whether the file is ready. | lists:read | 60 |
findclients_list_orders | Lists your purchased lists, newest first, up to 500 per list type. Older orders are on the Data Sources page. | lists:read | 30 |
findclients_get_download_link | Returns a link to the Excel file. The link works for 15 minutes without sign-in. | lists:read | 20 |
findclients_plan_schedule | Plans a schedule of new records (a set number or all new records), or a change to a schedule, with the cost per run. | lists:purchase | 10 |
findclients_create_schedule | Starts a planned schedule, or applies a planned change. | lists:purchase | 5 |
findclients_list_schedules | Lists your schedules. | lists:read | 30 |
findclients_manage_schedule | Pauses, resumes or deletes a schedule. | lists:purchase | 10 |
findclients_list_data_sources | Lists your files: uploads, purchased lists, report results, connected sheets and CRM lists. | data:read | 30 |
findclients_get_data_source | Profiles a file: rows, columns, fill rates, duplicates and the reports built from it. On your own file, it shows who has access. | data:read | 30 |
findclients_query_data_source | Runs one read-only SQL query on a file. | data:read | 30 |
findclients_get_data_source_download_link | Returns a short-lived link to download a file. | data:read | 20 |
findclients_create_upload_link | Makes a one-time page where you upload a customer file. | data:write | 10 |
findclients_get_upload_status | Tells whether you finished the upload page and which file it made. | data:read | 60 |
findclients_combine_data_sources | Combines files with the same columns, or all purchases of a workspace's list, into a new file. | data:write | 5 |
findclients_archive_data_source | Archives or restores a file that you own. | data:write | 10 |
findclients_plan_data_source_change | Checks an edit, share, unshare or delete of a file and shows the plan. It changes nothing. | data:write | 10 |
findclients_apply_data_source_change | Applies a plan that you confirmed. | data:write | 5 |
findclients_list_reports | Lists your look-alike reports, last changed first, and finds a report by name. | data:read | 30 |
findclients_create_report | Starts a look-alike report from a file and maps its columns. | data:write | 5 |
findclients_get_report | Shows a report's stage, progress, mapping, summary and next step. A business report adds its dashboard and leads. | data:read | 60 |
findclients_set_report_mapping | Changes which file column fills which field. | data:write | 20 |
findclients_update_report | Changes a report's sheet, title, industry or tags. industry: null clears the industry. | data:write | 20 |
findclients_quote_report | Prices the enrichment: customers, credits and balance after. | lists:purchase | 10 |
findclients_start_report | Enriches the customers of a quote. A retry of the same quote never charges twice. | lists:purchase | 5 |
findclients_generate_report | Builds the report from the enriched customers. | data:write | 5 |
findclients_ask_report | Answers a question about your customers from a finished report. | data:read | 10 |
findclients_query_report_sections | Reads the exact rows of one report section, with filters, sorting and totals. A business report also gives its lead rows (page by page) and dashboard. Consumer and property sections page in the report's order. | data:read | 30 |
findclients_query_report_records | Counts the enriched customers exactly, by any column. It never returns contact details. | data:read | 30 |
findclients_explain_report_metrics | Explains how FindClients measures each report figure. | catalog:read | 30 |
findclients_get_zip_areas | Gives the city, state and population of each ZIP code, as a property report reads them. It names the ZIP codes without consumer demographics. | catalog:read | 20 |
findclients_get_report_download_link | Returns a short-lived link to the report PDF, the enriched file or the image of a business report. | data:read | 20 |
findclients_build_list_from_report | Builds a prospect list like the report's customers and counts it. changes adds filters when the report alone is not enough. | lists:write | 10 |
- Five tools are marked as destructive:
findclients_purchase_list,findclients_start_report,findclients_create_schedule,findclients_manage_scheduleandfindclients_apply_data_source_change. Most AI apps ask you to approve each call. - A quote, a schedule plan and a file change plan last 15 minutes.
- The build tools take the same filters as the List Builder and change only the filters that the call names. To remove a filter, the assistant names it in
clear_filtersor sends it asnull. - With
dry_run, a build tool only counts. The assistant can compare a wider area or fewer filters without a change to your list. - Business lists take industries in words, for example
industries: ["dentists"]. FindClients changes them into industry codes from its catalog. - A report enriched in the last 30 days keeps its sheet.
- FindClients tells assistants never to invent a location or industry that you did not give.
- Every result has the tool's own fields, plus
next_stepandaccount. When the app can see your lists or buy, the result also hasbudget. It shows your balance, the app's limits, its spend today and what it can still spend.
Errors and troubleshooting
A refusal has error (the code), message (a sentence for you), retryable and next_step (what the assistant does next). A rate limit adds retry_after_seconds.
| Error code | Meaning | What to do |
|---|---|---|
FILTERS_INCOMPLETE | The list needs a location, or an industry for a nationwide list. Nothing was saved. | Give a location. |
INVALID_FILTERS, INVALID_ARGUMENTS | A filter or argument is not valid, or the tool does not take it. | The assistant corrects the value and tries again. |
NO_INDUSTRY_MATCH | No catalog industry matches the words. | Pick one of the closest industries in the message. |
ADDRESS_NOT_FOUND, ADDRESS_AMBIGUOUS | No street address matches, or the address matches several places. | Give the full address with city and state, or pick the place. |
WORKSPACE_NOT_FOUND, NO_LIST, WRONG_LIST_TYPE | The workspace ID is wrong, the workspace has no list yet, or it has another list type. | Ask for your workspaces, or use the build tool in the message. |
NO_RECORDS | No records match the filters. | Ask for ways to grow the list. |
JOB_B2B_COUNT_TIMED_OUT, JOB_B2C_COUNT_TIMED_OUT | The count did not finish, most often because the list is too broad. | Narrow the list, or try again. |
INSUFFICIENT_CREDITS | The purchase costs more credits than your wallet holds. | Buy fewer records, or add credits on findclients.ai. |
CREDITS_DISABLED | Credits are off for your account, so nothing can be bought. | Restore your subscription on findclients.ai. |
OVER_PURCHASE_LIMIT | The quote is more than the app's per-purchase limit. | Buy fewer records, or raise the limit under Connected apps. |
OVER_DAILY_LIMIT | The purchase would pass the app's daily limit. | Wait for the next UTC day, or raise the limit. |
QUOTE_NOT_FOUND, SCHEDULE_QUOTE_NOT_FOUND | The quote or schedule plan expired, or it belongs to another connection. | Ask for a new quote or plan. |
QUOTE_CHANGED | The list or the enrichment price changed after the quote. Nothing was spent. | Ask for a new quote. |
PURCHASE_IN_PROGRESS | Another call buys this quote now. | Wait a moment, then check the order. |
BUILD_IN_PROGRESS, REPORT_DRAFT_IN_PROGRESS | Another call changes this list, or makes a report of this file and sheet, now. | Wait a few seconds, then try again. |
PURCHASE_OUTCOME_UNKNOWN | The purchase may have started, but FindClients cannot tell yet. | Check the order or report before you try again. |
NOT_READY | FindClients is still building the list file. | Check the order again in a minute. |
ORDER_FAILED | The order failed and has no file. The message gives the reason. | Buy again only if you want to. |
ORDER_NOT_FOUND, EXPORT_NOT_FOUND | The order ID is wrong or not yours. | Ask for your orders. |
OWNER_ONLY | Only the owner can download or combine a shared purchased list from an app. | Download or combine it on the Data Sources page. |
SCHEDULE_NOT_SUPPORTED | Property lists cannot have a schedule. | Use a business or consumer list. |
JOB_SCHEDULE_ALREADY_EXISTS | The list has a schedule already. | Plan again with update_existing: true to change it. |
JOB_SCHEDULE_NOT_FOUND | The schedule ID is wrong, or someone deleted the schedule. | Ask for your schedules. |
DATA_SOURCE_NOT_FOUND | The file ID is wrong. | Ask for your files. |
NOT_SHARED, ALREADY_SHARED, USER_NOT_FOUND | The file is not shared with that person, has that access already, or no account has that email. | Check the teammate's sign-in email. |
DATA_SOURCE_NOT_QUERYABLE, DATA_SOURCE_QUERY_FAILED, DATA_SOURCE_QUERY_NOT_READONLY | The file is read live from its connection, or the query is not one valid read. | The assistant reads the file another way. |
CHANGE_NOT_FOUND, DATA_SOURCE_EDIT_STALE, SHARE_CHANGED | A file change plan expired or was used, or the file or access changed after the plan. | Ask the assistant to plan it again. |
UPLOAD_NOT_FOUND | The upload link expired after 30 minutes. | Ask for a new link. |
REPORT_NOT_FOUND | The report ID is wrong or not yours. | Ask for your reports. |
MAPPING_INCOMPLETE | The report's columns do not give what the enrichment needs, for example an address. | Tell the assistant which column has it. |
MAPPING_CONFLICT | Two columns would fill the same field. | Say which column keeps the field. |
NOT_SUPPORTED | The list or report type does not have that option. Examples: ranked columns for a property list, an image of a consumer or property report. | Use the option in the next step. |
REPORT_INPUT_LOCKED | The report was enriched in the last 30 days, so it keeps its sheet. | Start a new report for another sheet. |
REPORT_NOT_DRAFT, REPORT_NOT_READY, REPORT_RUNNING | The report is past the requested step, not at it yet, or running already. | Check the report. The assistant follows its next step. |
RUN_NOT_FINISHED | The last run of the report stopped before the end. | Start the report again in FindClients. |
REPORT_RECENT_REPORT_EXISTS | These customers were enriched in the last 30 days. | Use the report that the message names. |
REPORT_NOT_MEASURED, UNKNOWN_REPORT_ROW, ROLE_REQUIRED | The report has no audience or row for a list, or the row needs a job title. | Pick another segment or row, or give the job title. |
RATE_LIMITED | The app called one tool too many times in a minute. | Wait for retry_after_seconds. |
INTERNAL_ERROR | A step failed in FindClients. | Try again in a moment. |
A data service that is down or slow returns its own code with retryable: true. Try again in a moment.
- The sign-in page says that the request expired: the approval page lasts 30 minutes. Start the connection again in your AI app. If the page cannot load the request, select Try again.
- The AI app shows 401 or asks you to reconnect: the app was disconnected, or it did not use its refresh token for 30 days. Connect again.
INSUFFICIENT_SCOPE: the app asked for fewer permissions when it connected. Disconnect the app and connect it again.
Server details
Claude and ChatGPT find these values from the server URL. This list is for reference.
| Item | Value |
|---|---|
| MCP endpoint | POST https://api.findclients.ai/mcp (stateless) |
| Protected resource metadata | https://api.findclients.ai/.well-known/oauth-protected-resource/mcp |
| Authorization server metadata | https://api.findclients.ai/.well-known/oauth-authorization-server |
| Authorize | https://api.findclients.ai/oauth/authorize |
| Token | https://api.findclients.ai/oauth/token |
| Dynamic client registration | https://api.findclients.ai/oauth/register (public clients only) |
| Revoke | https://api.findclients.ai/oauth/revoke |
- A request without a valid token gets
401with aWWW-Authenticateheader that points to the protected resource metadata. If the client sent a token that the server refused, the header also haserror="invalid_token". - With a valid token,
GETandDELETEon/mcpreturn405. - PKCE with
S256is required. - The
resourceparameter is optional. If the client sends it, it must be the MCP endpoint URL. - A client identifies itself with a Client ID Metadata Document (an
httpsclient_idURL) or with dynamic registration. - A redirect URI must use
https, orhttpon a loopback host with any port. - Agents can read llms.txt for a short summary.
Privacy, security and support
FindClients.AI is a product of ProHelp, Inc. The AI app sees only what the permissions you approve allow.
- Sample records hide contact details and show names as initials. Full records come only with a purchase.
- Your FindClients password stays with FindClients. The AI app never gets it.
- Tokens are random strings. FindClients stores only their SHA-256 hashes.
- An access token lasts 1 hour. A refresh token lasts 30 days and changes at each use.
- If an app did not get the answer to a refresh, it can send the old refresh token one more time within 60 seconds. Any other reuse stops the whole connection, which blocks stolen tokens.
- FindClients logs each tool call with the app, the tool, the result and the credits spent.
- A link to a purchased list expires after 15 minutes and stops when you disconnect the app.
- A link to a file or report is a signed storage link. It expires after 1 hour, and a disconnect does not stop it earlier.
Read the Privacy Policy and the Terms of Service.
Support: support@findclients.ai · Privacy: privacy@findclients.ai