Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@usagentleads-mcp find masked contact previews for marketing directors at SaaS firms in Texas"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Official USAgentLeads developer resources. Documentation: https://www.usagentleads.com/docs.
Release status: API v2 and hosted MCP are implemented for the next application release. The application deployment is intentionally pending UI review. Public documentation and clients do not imply that those endpoints are already live. Existing one-time purchases and legacy v1 access continue unchanged.
Never commit an API key or real contact data. Use synthetic records in examples and tests. API access requires Growth (read) or Pro (read, unlock, MCP). Legacy Pro API retains v1 access and gains v2 read access.
Search and masked previews spend no record credits. One agent unlock costs one credit; a brokerage costs two. Unlocks share the dashboard balance. Reuse the same UUID idempotency key and identical payload after a timeout. Do not create another key until the prior outcome is resolved.
Licensed under MIT. This license covers client code and documentation, not the licensed contact dataset.
Connect a Streamable HTTP client to https://www.usagentleads.com/api/mcp, with Authorization: Bearer <API key>. Pro is required. OAuth is not part of this release. Use a client that supports bearer headers; store the key outside version control.
Related MCP server: genpark-personal-vault-zero-knowledge-sanitizer-skill
npm ci
export USAGENTLEADS_API_KEY='your-key'
npm startConfigure your client to run node /absolute/path/usagentleads-mcp/src/index.mjs and supply the key through its environment. The bridge calls the REST API; REST plan restrictions are enforced on each request. Tools are defined in tools.json.
unlock_records requires approval for the selection and maximum credits, confirmCreditSpend: true, and a saved UUID idempotency key. Reuse the same key and payload on retries. Tool annotations are client hints, not proof of approval. create_export prepares a credential-free URL; downloading it with your bearer key generates the suppression-aware CSV and audit record.
Run npm test for offline safety checks.
Count matching agents or brokerages. Searching spends no record credits.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| filters | No | state, countyFips, city (requires state), zip, mustHave, activeLicense, organization, orgType. See API docs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context — counting consumes no record credits — but says nothing about the shape of the count result, filter combination behavior, or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the operation is front-loaded and the credit-cost note follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter counting tool with full annotation coverage and no output schema, the definition covers purpose, cost implications, and the population enum. What's missing is the exact return shape and filter-combination semantics — modest gaps rather than blocking ones.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: the 'filters' object lists its fields (with 'See API docs' as a hand-off) while the required 'kind' parameter has no description. The description only echoes the kind enum ('agents or brokerages') and adds no meaning about how filters combine or what happens if unsupported fields are passed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb-plus-resource: 'Count matching agents or brokerages.' It tells the agent what is counted and the two population types. It doesn't differentiate itself from siblings like 'coverage' or 'preview_records', so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Searching spends no record credits' implies the tool is the free/exploratory option before spending credits on unlock_records, but the agent must infer that comparison. No sibling is named and no when-not-to-use condition is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get release date, catalog coverage and data limitations. No record credits spent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: the call is free (no record credits) and that the response surfaces data limitations, which an agent needs to interpret results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler, front-loading what is returned before the cost note. Nothing is repeated from the annotations or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and full annotation coverage, the description supplies what the agent needs: the three kinds of information returned plus the zero-cost property. Only the shape of the 'data limitations' output is unstated, a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly makes no attempt to describe argument semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get') and the concrete payload: release date, catalog coverage, and data limitations. The name 'coverage' alone is ambiguous, but the description resolves it; sibling differentiation is only partial, relying on the implicit contrast between a metadata call and record-consuming calls like unlock_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'No record credits spent' hints at when to prefer this over credit-consuming siblings such as unlock_records or preview_records, but the connection is left to inference. There is no explicit 'call this before/after X' or stated exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare an authenticated CSV download request for owned records. The download applies your suppression list and records an export audit. No credits spent; do not include your API key in a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| list | No | ||
| template | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description adds genuinely new context: authentication is required, the caller's suppression list is applied to output, an export audit is logged, and no credits are consumed. Minor tension: 'records an export audit' implies a server-side write while readOnlyHint=true is declared, though this is audit logging rather than record mutation. It still omits what is actually returned (URL vs job id) and any expiry behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the core action front-loaded and no filler. The trailing API-key warning is slightly tangential but is a legitimate security constraint, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter export tool with zero schema description coverage and no output schema, the description leaves key gaps: what the call returns (download URL, token, job id), whether the link expires, and how template/list interact. The caller can guess the high-level intent but not the mechanics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and two of three parameters are enums (kind, template) whose allowed values and effects are invisible in the description. 'Owned records' hints weakly at the list parameter, but nothing explains what template does (column mapping for the named CRM?) or why list scopes the export.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('Prepare an authenticated CSV download request for owned records'), so an agent understands the outcome without opening the schema. It does not differentiate from siblings such as preview_records, owned_records, or coverage, nor does it say what 'kind' selects (agents vs brokerages), leaving some overlap ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'No credits spent' implies a contrast with the credit-consuming unlock_records sibling, and 'do not include your API key in a URL' is a usable operational caveat. However, there is no explicit 'use this when / use X instead' guidance and no stated prerequisites for choosing between this and preview_records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the shared dashboard/API credit balance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation. The description adds that the balance is 'shared' for the dashboard/API, which is useful scoping context, but it does not mention permissions, rate limits, or what the returned balance includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted wording. It states the operation and scope immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with rich safety annotations, the description is sufficient to invoke it correctly. It does not describe the return shape, but the operation is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so there is nothing for the description to clarify. The baseline for a parameterless tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: checking the shared dashboard/API credit balance. It is clear what the tool does, though it does not explicitly differentiate itself from the sibling tools, which mostly concern records and exports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool, when not to use it, or which sibling tool to prefer. Usage is only implied by the name and the phrase 'credit balance.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read previously unlocked records. No record credits spent. Returns at most 100 records per page.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| kind | No | ||
| list | No | ||
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral facts: no credits are consumed and results are capped at 100 records per page. That pagination and cost information is exactly what the agent needs and is not in the structured fields. It still doesn't describe ordering or whether the page cap interacts with pageSize.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: purpose, cost model, and result limit. The most decision-relevant facts come first, with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no output schema and no parameter descriptions, the definition leaves too much unknown: what q matches, what kind filters, what the list UUID references, default page behavior, and what a record contains. It is adequate for the cost/pagination story but not for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 5 parameters, so the description must carry the load and it says nothing about q, kind, list, or page. Only 'at most 100 records per page' loosely gestures at pageSize, and even that omits the 25/50/100 enum and the meaning of the 'list' UUID parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read previously unlocked records'), and the word 'previously' scopes it to already-unlocked data, which implicitly separates it from unlock_records and preview_records. It doesn't name siblings explicitly, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Read previously unlocked records' implies the usage context (existing unlocked data rather than fresh unlocks), and 'No record credits spent' reinforces that this is the free follow-up path. However, no alternative tool is named and there are no explicit conditions or exclusions telling the agent when to pick this over coverage, count_records, or preview_records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview masked agents or brokerages. Searching spends no record credits.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| filters | No | state, countyFips, city (requires state), zip, mustHave, activeLicense, organization, orgType. See API docs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds two things annotations don't convey: results are masked, and searching consumes no record credits — a meaningful cost/behavior disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the core action is front-loaded and the cost note follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple preview tool with full safety annotations, the description covers purpose and cost but not what a 'preview' actually returns (sample masked records? counts?), which matters since there is no output schema. Adequate but with a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description says nothing about 'kind' or the nested 'filters' object. The schema already documents the kind enum and enumerates filter fields, so the description adds no semantic value beyond structured data, matching the baseline for partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Preview') and resource ('masked agents or brokerages'), making it distinguishable from siblings like unlock_records by signaling that data comes back masked. It stops short of naming any sibling explicitly, so sibling differentiation is only implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Searching spends no record credits' hints at when to use this tool (cheap exploration before paying to unlock), but it never states that relationship explicitly or names unlock_records/count_records as alternatives. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SPENDS CREDITS: one per agent, two per brokerage. Obtain the user's approval for the exact selection and maxCredits before calling. Reuse the SAME UUID idempotencyKey and parameters on retries; never automatically create a new key after a timeout. Already-owned and contactless records cost zero.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| filters | No | ||
| ordinals | No | ||
| quantity | No | ||
| releaseId | Yes | ||
| maxCredits | Yes | ||
| idempotencyKey | Yes | ||
| confirmCreditSpend | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses credit costs, approval requirements, idempotency key reuse, and zero-cost cases, adding substantive context beyond destructive=true and idempotent=true. It still does not explain what unlocking does to the records or whether access is permanent, but annotations already cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The credit-spend warning is front-loaded, and each sentence covers a distinct operational concern: cost, approval, idempotent retry, and zero-cost exceptions. There is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-stakes credit-spending tool with no output schema and no parameter documentation, the description covers approval and idempotency but leaves the selection model and several parameters opaque. An agent could understand the safety constraints but not confidently construct the exact selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema descriptions across 8 parameters, the description only clarifies maxCredits, idempotencyKey, and kind indirectly. releaseId, filters, ordinals, quantity, and confirmCreditSpend remain unexplained, which is insufficient for a destructive credit-spending operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys that the tool spends credits to unlock agent/brokerage records, but never states the operation in a direct verb+resource phrase, leaving the actual unlock action implicit. It also does not distinguish this tool from siblings such as preview_records or owned_records, so selection relies heavily on the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a prerequisite (user approval for the exact selection and maxCredits) and retry guidance, but does not say when to choose this over preview_records or owned_records. Usage is implied rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0count_recordscoveragecreate_exportcredit_balanceowned_recordspreview_recordsunlock_recordsScored across 7 tools
Each tool targets a distinct stage of the lead-data workflow: metadata, counting, masked preview, balance, owned records, unlocking, and export. The no-credit tools (count_records, preview_records, coverage) are clearly differentiated by output type, and unlock_records is clearly separated from preview_records by cost and result.
All names use snake_case and are readable, but the pattern is not uniformly verb_noun: owned_records is adjective_noun, while coverage and credit_balance are noun phrases. The deviations are minor and still predictable within the domain.
Seven tools is well-scoped for a lead-data marketplace, with each tool earning its place by covering a distinct workflow step. There is no obvious redundancy or missing operational layer that would require more tools.
The surface covers the core lifecycle: coverage check, count, preview, credit balance, unlock, read owned records, and export. Minor gaps exist around suppression-list management and export history/status, but agents can work around these for the main purchase workflow.
Search B2B contacts and business leads through an OAuth-secured MCP server with masked results.
Search and update Records and Lists, import and export CSVs, and run enrichment in Connie.
Authenticated public evidence search, verification, research jobs, exports, and webhooks.
Discover audiences, build segments, match and deliver data. Some actions may incur billable usage.
