@preceptai/mcp-server

Precept MCP Server

Expose Precept's B2B contact and company intelligence tools directly to AI assistants like Claude Desktop, Cursor, and ChatGPT.

This server implements the Model Context Protocol (MCP) and wraps Precept's core API. All operations are non-blocking — jobs return immediately with an enrichment_id, and results are polled via a separate status tool. This avoids LLM client timeouts on long running jobs.

Supports dual-transport bootstrapping:

• stdio — for local integrations (Claude Desktop, Cursor)
• Streamable HTTP — for remote hosting (ChatGPT, enterprise agents)

Tools

Tool	Description
precept_search_leads	Search for leads using natural language (e.g. "Marketing heads at SaaS companies in California"). Optionally enrich with verified emails, phone numbers, and AI insights. Returns a jobId.
precept_enrich_leads	Enrich a specific list of contacts using LinkedIn URLs or name + company details. Returns verified emails, phones, professional summary, top problems, and strategic initiatives. Returns a jobId.
precept_get_company_insights	Retrieve structured insights for specific companies — decision makers, technology stack, revenue, funding, employee counts, department ratios, and custom queries. Returns a jobId.
precept_search_companies	Discover companies using natural language queries and optionally enrich with insights. Returns a jobId.
precept_get_job_status	Poll the status and retrieve results of any job. Poll every 4s for up to 150 attempts (~10m) while in progress and update user every 15 polls (~1m). Returns processing (with progress) or completed (with full data).
precept_check_credits	Check the remaining credit balance for your Precept account and server version status.
precept_check_version	Check the running server version against the latest published release to see if a connector update is available.

How It Works (Async Job Pattern)

User → "Find CTOs at fintech startups in London"
  ↓
LLM calls precept_search_leads → returns { enrichment_id: "job_123" }
  ↓
LLM continuously polls precept_get_job_status("job_123") every 4 seconds for up to 150 attempts (~10 minutes)
  ↓
LLM gives progress/status updates to the user every 15 polls (~1 minute)
  ↓
If still processing → LLM keeps polling every 4 seconds
If completed → LLM receives full results with contact details and presents them to the user
If reaches 150 attempts (~10m) still in progress → LLM asks user to check back in a few minutes as it is taking longer than usual

Client Setup

The Precept MCP server is designed to run directly inside your LLM client.

Prerequisites

• Node.js v20+
• Precept API Key — generate one from the Precept Developer Dashboard

1. Claude Desktop

Add this config to your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "precept": {
      "command": "npx",
      "args": ["-y", "@preceptai/mcp-server"],
      "env": {
        "PRECEPT_API_KEY": "your_precept_api_key_here"
      }
    }
  }
}

(Make sure to completely restart/quit Claude Desktop after editing this file).

2. Cursor

Go to Settings → Features → MCP:

• Click + Add New MCP Server
• Name: Precept | Type: command
• Command: npx -y @preceptai/mcp-server
• Click Save
• Ensure your terminal has the PRECEPT_API_KEY environment variable set, or add it to a local .env file where Cursor is opened.

3. Codex

Run the following CLI command:

codex mcp add precept --env PRECEPT_API_KEY=your_api_key_here -- npx -y @preceptai/mcp-server

(Or add to ~/.codex/config.toml under [mcp_servers.precept] if you prefer manual configuration).

Remote Setup: Streamable HTTP Mode

For remote deployment (e.g., ChatGPT Web/Desktop or hosted agents), run the server over Streamable HTTP:

1. Configure Environment

Create a .env file in the project root:

PRECEPT_API_KEY=your_precept_api_key_here
MCP_TRANSPORT=http
PORT=3000
ALLOWED_HOSTS=your-mcp-domain.com

2. Start Server

npm start

The server will expose a stateless MCP endpoint at http://your-domain.com:3000/mcp.

Environment Variables

Variable	Default	Description
PRECEPT_API_KEY	(required)	Your Precept API key from the Developer Dashboard.
MCP_TRANSPORT	stdio	Transport mode: stdio (local) or http (remote Streamable HTTP).
PORT	3000	Port for HTTP mode.
ALLOWED_HOSTS	localhost,127.0.0.1	Comma-separated allowed hosts for DNS rebinding protection (HTTP mode only).

Credits & Pricing

All Precept API operations consume credits. Key costs:

Operation	Cost
Lead Search (no insights)	0.1 credits/lead
Lead Search (with insights)	1.1 credits/lead
Lead Enrichment	1 credit/lead
Contact Details (email)	+1 credit/lead
Contact Details (phone)	+10 credits/lead
Company Base Insight	1 credit/company
Custom Query	0.2 credits/query/company
Decision Makers	0.5 credits/person/role
Technology Stack	2 credits/company
Revenue	5 credits/company
Post Activity Filter	+5 credits/lead

See the full Precept Credits Documentation for details.

Links

• Precept Website
• Precept API Documentation
• Developer Dashboard
• Model Context Protocol

License

MIT