DealSurface MCP Server

MCP server for the DealSurface sales intelligence API. Gives AI agents access to enterprise-grade sales prospecting, deal strategy, and lead generation/outreach – all backed by clear evidence of need for your product.

Installation

Claude Desktop / Claude Code

Add to your MCP client configuration:

{
  "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. Defaults to https://dealsurface.com |

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 get_leads 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 all products configured for your team | | get_product | read | Free | Get product detail by ID | | list_prospects | read | Free | List assessed companies ranked by deal score | | get_prospect | read | Free | Full prospect analysis with evidence excerpts | | search_excerpts | read | Free | Filter SEC filing evidence excerpts | | get_leads | outreach | Conditional | Get lead candidates; billed only when fresh org-chart data is fetched | | craft_outreach | outreach | Billed | Generate personalized email or LinkedIn outreach copy |

Billing Details

• Free tools (list_products, get_product, list_prospects, get_prospect, search_excerpts) do not consume credits.
• get_leads is charged only when the response reports generation_source=org_fresh. Cached results 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.

Recommended Agent Flow

1. Call list_products to see available products.
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_leads with product_id and ticker to find decision-makers.
5. Call craft_outreach with a selected lead to generate personalized outreach.

Lead Selection in craft_outreach

You can personalize outreach using either:

• selected_lead — Full lead object from get_leads response (preferred)
• lead_selector — Lightweight selector: {"node_id": "..."}, {"level": "vp"}, or {"full_name": "Jane Doe", "level": "director"}

If both are provided, selected_lead takes precedence. If no match is found, outreach still succeeds but includes guidance to call get_leads 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. Lead 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 18 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.