@dealsurface/mcp-server

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.

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. 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 generate_dealmap, override_stakeholder_role, 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 configured for your team (include_disabled optionally includes disabled metadata)
get_product	read	Free	Get active product detail by ID (include_disabled optionally includes disabled metadata)
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_dealmap	read	Free	Read the buying committee DealMap (stakeholder roles, org hierarchy)
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
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, get_dealmap, override_stakeholder_role) do not consume credits.
• generate_dealmap is charged only when 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

• Call list_products to see active products available for operational tools.
• Call list_prospects with a product_id to find top-ranked companies.
• Call get_prospect for detailed analysis on a specific company.
• Call get_dealmap to see the buying committee (or generate_dealmap if empty).
• Call craft_outreach with a selected stakeholder to generate personalized 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 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.