DealSurface MCP Server

MCP server for the DealSurface sales intelligence API. Gives AI agents access to enterprise-grade sales prospecting, buying committee analysis, and outreach – all backed by clear evidence of need for your product.

What's new in 2.7.1

• Bug fixes and reliability improvements.

What's new in 2.7.0

• list_prospects accepts complaint_line, min_complaint_index and min_complaints, and sort_by: "complaint_index" can rank by a single CIS policy line. Rows carry complaints.by_line_of_business.
• get_prospect returns a family complaint rollup (scope: "family", with a per-carrier by_entity breakdown) for parents without their own NAIC cocode, and observations flag low_sample below 10 complaints.
• account_verdict can now be "nurture": the company fits the product but no current trigger is evidenced. deprioritize is only used at a deal score of 1 or 2. Group-grain detail (narrative_scope: "group") now carries group_verdict with the same values.
• Settled buying signals weigh more in deal_score (+20 potential, +40 strong; previously +10 / +20), applied as each product is next processed.

What's new in 2.6.0

• craft_outreach uses the product's configured outreach template by default and accepts an optional template_key.
• New free list_outreach_templates tool lists active alternatives when a user asks to explore or change outreach style.
• Template listings report type, channel, and credit cost. Deterministic static messages are free; generation prompts and a static AI hook cost one credit on success.
• Outreach responses identify the exact template key, version, type, source, and resolution path used for the draft.
• MCP can browse, select, and use templates. Creation, editing, and default changes remain in the DealSurface Outreach → Templates UI.
• Excerpt results can include additive company_event metadata (a materially current, product-relevant event) with date_is_approximate when the date is anchored to a source publication or call date.

Upcoming API behavior change: prospect population

When this API update is deployed, omitting include_private in list_prospects or get_prospect will request the team's entitled population instead of the previous public-only default. This is an intentional behavior change: entitled teams may see more companies and different ranks/totals. Existing MCP clients are affected by the API deployment even without a package upgrade.

To preserve public-only lists and public-company ranks, explicitly pass include_private: false. Private-company detail continues to use its entitled private-inclusive rank population. Team access restrictions remain enforced. The response population field explains the requested policy and rank scope.

What's new in 2.0.0

Version 2.0.0 targets the relaunched DealSurface REST API v2 (/api/v2). Older server versions target /api/v1, which now returns 410 Gone — upgrade to keep working. Highlights:

• Corporate-family prospect lists. list_prospects returns one row per corporate family with entity_count/matched_entity_count, premium and complaint summaries, and a total_groups/total_entities envelope (replacing total_count).
• Rich filtering. New list_prospects filters: assessment status, insurance entity type, ownership, premium bands, lines of business (matches ANY), licensed states (matches ALL), name search (q), and new sort keys including complaint_index. Vocabularies are embedded in the tool schemas as enums so invalid values are rejected client-side with the accepted set shown.
• Strict filters, visible exclusions. Families with no data for an applied insurance filter are excluded and counted in excluded_no_data_groups.
• Subsidiary drill-down. get_prospect accepts any hierarchy.children[].ticker; dealmap/outreach tools resolve subsidiary tickers upward to the corporate family and say so in the response.
• New tool set_top_pick to mark/unmark a stakeholder as the top pick for their buying-committee role.
• framework_category removed from search_excerpts (both as a filter input and as a response field on excerpts).
• Detail responses gain company_info, per-year premium/complaints series, hierarchy, narrative_scope, and excerpt_count; embedded excerpts are capped at 20 (use search_excerpts for the rest).
• A 503 from prospect/excerpt tools means the product's projection is not ready (rebuilding or stale_keywords) — never "no prospects".
• Every request sends User-Agent: dealsurface-mcp/<version>.

Installation

Claude Desktop / Claude Code

Add to your Claude Desktop configuration file (claude_desktop_config.json):

Tip (Mac): Click the Claude menu in your system menu bar (not inside the Claude window), go to Settings → Developer, then click "Edit Config" — this opens the file directly, and creates it if it doesn't exist yet.

{
  "mcpServers": {
    "dealsurface": {
      "command": "npx",
      "args": ["-y", "@dealsurface/mcp-server"],
      "env": {
        "DEALSURFACE_API_KEY": "ds_live_your_api_key_here"
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio transport can use this server. Set DEALSURFACE_API_KEY in the environment and run:

npx -y @dealsurface/mcp-server

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | DEALSURFACE_API_KEY | Yes | Your DealSurface API key (starts with ds_live_ or ds_test_) | | DEALSURFACE_API_URL | No | Override the API base URL (origin only — the server appends /api/v2). Defaults to https://dealsurface.com. Useful for pointing at a staging environment. |

API Key Scopes

Your API key must have the appropriate scopes for the tools you want to use:

• read — Required for all tools
• outreach — Additionally required for generate_dealmap, override_stakeholder_role, list_outreach_templates, and craft_outreach

Visit the API Key page in your DealSurface account to manage API keys and scopes.

Available Tools

| Tool | Scope | Billing | Description | |------|-------|---------|-------------| | list_products | read | Free | List active products with keywords, sources, industries, and segment targeting (include_disabled optionally includes disabled metadata) | | get_product | read | Free | Get active product detail by ID, including target_segments (include_disabled optionally includes disabled metadata) | | list_prospects | read | Free | List prospect corporate families with rich filters (entity type, ownership, premium, lines of business, licensed states, name search) and sorts | | get_prospect | read | Free | Full prospect analysis: company info, premium/complaint history, hierarchy, findings, and capped evidence excerpts. Accepts subsidiary tickers | | search_excerpts | read | Free | Filter SEC filing evidence excerpts | | list_outreach_templates | read + outreach | Free | List active team outreach templates and the product default | | get_dealmap | read | Free | Read the buying committee DealMap (stakeholder roles, org hierarchy). Subsidiary tickers resolve to the corporate family | | generate_dealmap | outreach | Conditional | Generate or refresh the buying committee DealMap; billed only on fresh org-chart fetch | | override_stakeholder_role | outreach | Free | Override an AI-assigned stakeholder role | | set_top_pick | read | Free | Mark/unmark a stakeholder as the top pick for their buying-committee role | | craft_outreach | read + outreach | 0–1 credit | Create email or LinkedIn outreach from the product default or an explicit static message or generation prompt |

Billing Details

• Free tools (list_products, get_product, list_prospects, get_prospect, search_excerpts, list_outreach_templates, get_dealmap, override_stakeholder_role, set_top_pick) do not consume credits.
• generate_dealmap is charged 10 credits for successful results with generation_source=org_fresh or org_fresh_empty (a fresh empty org result supplemented with people). Cached results (org_cache or annotated_cache_hit) are free. The force_refresh parameter bypasses the cache and should only be used when explicitly requested.
• craft_outreach consumes team credits when the API returns a valid result.
• If your team does not have enough credits, the server returns an error with remaining and required credit details.
• See API docs and pricing page for latest credit costs.

Rate Limits and Parallelism

Limits apply per API key over a sliding 60-second window:

| Limit | Applies to | Per minute | |-------|------------|------------| | General | Every tool call | 120 | | DealMap generation | generate_dealmap | 20 | | DealMap generation (workspace, all keys combined) | generate_dealmap | 40 | | Outreach | craft_outreach | 60 |

When working through a list of companies or leads, run independent calls in parallel instead of one at a time: up to 10 generate_dealmap calls at once (each takes roughly 15–45 seconds) and up to 10 craft_outreach calls at once. On a 429, wait the Retry-After seconds and retry only the rejected calls.

Before generating, call get_dealmap (free and fast) and skip companies that already have a DealMap; de-duplicate tickers that resolve to the same corporate family. generate_dealmap returns the full DealMap, so no follow-up get_dealmap call is needed.

Recommended Agent Flow

1. Call list_products to see active products available for operational tools.
2. Call list_prospects with a product_id to find top-ranked companies.
3. Call get_prospect for detailed analysis on a specific company.
4. Call get_dealmap to see the buying committee (or generate_dealmap if empty). For many companies, run these in parallel batches (see Rate Limits and Parallelism).
5. Call craft_outreach with a selected stakeholder and omit template_key to use the product default. For many leads, run these in parallel batches too.
6. Call list_outreach_templates only when the user asks to explore or change the outreach style, then pass the chosen returned template_key to craft_outreach.

Stakeholder Selection in craft_outreach

You can personalize outreach using either:

• selected_lead — Full stakeholder object from get_dealmap response (preferred)
• lead_selector — Lightweight selector: {"node_id": "..."}, {"level": "vp"}, {"full_name": "Jane Doe", "level": "director"}, or {"stakeholder_role": "Economic Buyer"}

If both are provided, selected_lead takes precedence. If no match is found, outreach still succeeds but includes guidance to call get_dealmap first.

Troubleshooting

"DEALSURFACE_API_KEY environment variable is required"

Make sure DEALSURFACE_API_KEY is set in your MCP client configuration.

"403 Forbidden" or "Insufficient permissions"

Your API key may not have the required scope. Read-only tools need the read scope. DealMap generation and outreach tools need the outreach scope.

"402 Insufficient credits"

Your team has run out of credits for billed operations. The error message includes your remaining balance and the credits required. Contact your account administrator.

"429 Too Many Requests"

Some endpoints are rate limited more heavily than others. See API documentation for more details.

Requirements

• Node.js 20 or later
• A DealSurface API key with appropriate scopes

License

This package is proprietary commercial software and is not open source. Use is limited to authorized DealSurface customers and other users expressly approved by DealSurface, and is governed by the applicable DealSurface customer agreement, API terms, or Terms of Service: https://dealsurface.com/terms.

The package and related services are provided "as is" and without warranties or guarantees. See LICENSE for details.

Prospect population and DealMap failures

Prospect lists and detail ranks default to the team-entitled population. Use include_private: false for public-only lists or public-prospect ranks. Private prospect detail retains private-inclusive ranking. The additive population field identifies the rank scope: lists rank filtered families, while detail ranks unfiltered families. On lists, included_if_entitled describes the policy; it does not guarantee private rows or override the live team entitlement. excluded_no_data_groups counts only insurance-filter coverage exclusions.

DealMap generation permits 20 requests per minute per API key (40 per workspace); on a 429, wait the Retry-After seconds and retry only the rejected calls. A 422 distinguishes unresolved company identity (company_identity_unresolved) from unavailable organizational information (dealmap_data_unavailable). Neither is a temporary-service or timeout diagnosis. After a timeout, read the current DealMap before retrying; background completion is not guaranteed.