Skip to main content

MoltSets Quick Start Guide

Everything you need to make your first MoltSets API call, from creating an API key to getting a real response back.

MoltSets can be connected to your workflow in two ways: through our API or through our MCP server. Which one you use depends on what you're building and how technical you want to get.

Path 4: Use the CLI


Path 1: Connect via API

Who this is for

Developers and technical users who want full control, plan to build custom integrations, or need to embed MoltSets data into their own systems, scripts, or products.

Use case

You're writing code that calls MoltSets directly, whether that's a one-off script, a production integration, or a feature inside your own app.

MoltSets API Setup Instructions

Getting started

  1. Go to API Keys to generate your API key.

  2. Head to our developer docs at https://developer.moltsets.com to see full endpoint documentation.

Each API has a playground built into the docs, so you can test requests and see live responses before writing any code.

Note: User-Agent can be any non-empty value — MoltSets doesn’t validate its contents, only that it’s present. Requests without one are rejected with a 403 (forbidden). See Errors.


Path 2: Connect an AI agent via MCP

Who this is for

Users who want to work with MoltSets conversationally inside Claude, without writing code. This is the faster path if you're using Claude for prospecting, enrichment, or research and want MoltSets tools available directly in chat.

Use case

You want Claude to call MoltSets tools (lookups, enrichment, search) as part of a normal conversation, agentic workflow, or Claude Code session, instead of hitting the API yourself.

Before you start

Before you start, you'll need your MoltSets Connector credentials (OAuth Client ID and Client Secret). Get these by logging into app.moltsets.com and going to API Keys to create a new connector.

The setup steps depend on which Claude client, or other MCP client, you're using.

MoltSets MCP Setup Instructions

If you're using Claude.ai — Personal account (Free, Pro, or Max)

  1. Go to Customize → Connectors.

  2. Click +, then Add custom connector.

  3. Paste this into Remote MCP server URL:

    https://mcp.moltsets.com/mcp
  4. Click Advanced settings and enter your OAuth Client ID and Client Secret.

  5. Click Add.

Free accounts are limited to a single custom connector. Pro and Max accounts can add multiple.


If you're using Claude.ai — Team or Enterprise account

Only an Owner or Primary Owner of your Claude Team/Enterprise account can add a custom connector for the organization. Once it's added, each member connects individually, and Claude only ever accesses data that member is authorized to see.

Before you begin

You will first need to invite your Owner or Primary Owner of your Claude Team/Enterprise account to MoltSets as they will need to have a MoltSets user in order to complete the connection process.

Owner or Primary Owner — add the connector:

  1. Go to Organization settings → Connectors.

  2. Click Add.

  3. Hover over Custom, then select Web.

  4. Paste this into Remote MCP server URL:

    https://mcp.moltsets.com/mcp
  5. Click Advanced settings and enter the OAuth Client ID and Client Secret.

  6. Click Add.

Each member — connect to it:

  1. Go to Customize → Connectors.

  2. Find the MoltSets connector (marked Custom).

  3. Click Connect and complete authentication.


If you're using Claude Desktop

Claude Desktop shares the same connectors as your Claude.ai account, so if you've already added MoltSets there, no further setup is needed here.

Personal account (Free, Pro, or Max):

  1. Go to Customize → Connectors.

  2. Click +, then Add custom connector.

  3. Paste this into Remote MCP server URL:

    https://mcp.moltsets.com/mcp
  4. Click Advanced settings and enter your OAuth Client ID and Client Secret.

  5. Click Add, then restart Claude Desktop so it picks up the connector.

Team or Enterprise account:

Same organization-level setup as Claude.ai above (an Owner adds the connector once), then each member goes to Customize → Connectors in Claude Desktop, finds MoltSets, clicks Connect, and restarts the app.

Tool permissions:

By default, all MoltSets tools are set to Needs Approval, so Claude will prompt before using each one the first time. To change this in bulk, go to Customize → Connectors, click Configure beside MoltSets, and use the bulk change tool to set tools to Always Allow. Individual tools can also be set to Blocked if you want to restrict access.


If you're using Claude Code

Run this in your terminal, replacing the placeholders with your credentials:

claude mcp add --transport http moltsets https://mcp.moltsets.com/mcp \   --client-id YOUR_CLIENT_ID \   --client-secret

The --client-secret flag takes no value. Claude Code will prompt you for it, or you can set it via the MCP_CLIENT_SECRET environment variable.

By default this adds MoltSets at the local scope (current project only). Add --scope user to make it available across all your projects:

claude mcp add --transport http moltsets https://mcp.moltsets.com/mcp \   --scope user \   --client-id YOUR_CLIENT_ID \   --client-secret

Claude Code will open a browser window for you to approve access on the MoltSets consent screen. Once approved, your token is stored and managed automatically.

Personal account:

The command above works as-is.

Team or Enterprise account:

Only admins can add MCP servers to Claude Code on business plans. If you sign into Claude Code with your Claude.ai account, any MoltSets connector already added there is available automatically, no claude mcp add needed. Either way each seat authorizes over OAuth in the browser, so there's no need to distribute ms_ API keys across an organization.


If you're using another MCP client

Any MCP client that supports remote servers over HTTP can connect — CLI agents, desktop apps, and IDE extensions included.

  1. Add https://mcp.moltsets.com/mcp as a remote MCP server in your client.

  2. When the client asks for OAuth credentials, paste the Client ID and Client Secret from the API Keys page at app.moltsets.com. Clients that register themselves can skip this step.

  3. Approve access on the MoltSets consent screen when the browser opens. The client stores the token from there; re-run the flow if it expires.

Clients that run in a terminal complete this on a local port — http://127.0.0.1:<port>/callback and its localhost and [::1] equivalents are supported, so no HTTPS callback is needed on your machine.

Endpoints, scopes, and redirect URI rules are discoverable directly from the server at https://mcp.moltsets.com/.well-known/oauth-protected-resource.


Path 3: Use the Chrome Extension

Who this is for

Sales, recruiting, and marketing users who want MoltSets data while browsing LinkedIn, without writing code or opening Claude. This is the quickest path if you research prospects one at a time and want results right on the profile you’re viewing.

Use case

You’re on a LinkedIn profile and want to pull a business email, full business profile, or mobile phone number in a click, see anything you’ve already enriched, and send the contact straight to HubSpot or Salesforce.

Before you start

You’ll need a MoltSets account and a Chrome-based browser. Mobile phone lookups require a phone token subscription; if your account doesn’t have one, the extension will prompt you to add it. To send contacts to HubSpot, you’ll also need a HubSpot private app access token. Salesforce uses your existing browser login, so there’s nothing extra to set up.

MoltSets Chrome Extension Setup Instructions

  1. Install the extension
    Open the Chrome Web Store listing and click Add to Chrome.

  2. Open the side panel
    Click the MoltSets icon in your Chrome toolbar. Pin it from the extensions menu so it’s always one click away.

  3. Connect your API key
    Click I already have an account, paste your API key, and click Connect. MoltSets keys start with ms_. Find or create a key in the MoltSets app. See Authentication for details.

  4. Allow LinkedIn access

    Click Allow LinkedIn access and accept the Chrome prompt. Chrome describes this as reading and changing your data on linkedin.com, but the extension only reads the address of your LinkedIn tab. Nothing on the page is read or changed.


Path 4: Use the CLI

Who this is for

RevOps, growth, and data-minded sales and marketing users who are comfortable in a terminal and work with lists rather than single profiles. It also suits anyone running MoltSets from scripts, scheduled jobs, or an AI agent like Claude Code. This is the quickest path if you have a CSV to enrich or a search that returns hundreds of records.

Use case

You have a CSV of LinkedIn URLs, names and companies, or emails, and want verified business emails, mobile phones, or full profiles added as new columns in one command. Or you want to pull every VP of Sales at 51 to 200 person US companies straight into a CSV, leaving out accounts you already have. The CLI handles batching, dedupe, fair use waits, and resuming if a job stops partway through.

Before you start

You’ll need a MoltSets account, an API key (keys start with ms_), and Node.js 18 or later. You can run the CLI with npx moltsets without installing anything, or install it globally with npm install -g moltsets. Run moltsets login to save your key, or set MOLTSETS_API_KEY for scripts and agents, then run moltsets whoami to check your setup. Mobile phone lookups need phone tokens, and the CLI stops cleanly and keeps your partial results if you run out. Run a --dry-run before any big job to see the expected usage against your token balance and fair use headroom.

MoltSets CLI

  1. Connect to MoltSets in your CLI

    # Run without installing
    npx moltsets --help

    # Or install globally
    npm install -g moltsets

  2. Example Commands

    # Plan, token balance and fair use headroom (free)
    moltsets whoami

    # One lookup
    moltsets linkedin_to_best_email \
    --linkedin-url https://linkedin.com/in/john-smith-123

    # Count rows and check headroom, no paid calls
    moltsets enrich leads.csv --tool linkedin_to_best_email \
    --column linkedin --dry-run

    # First 10 rows only
    moltsets enrich leads.csv --tool linkedin_to_best_email \
    --column linkedin --limit 10 --out sample.csv

    # The whole file
    moltsets enrich leads.csv --tool linkedin_to_best_email \
    --column linkedin --out enriched.csv

  3. Teach your agent the CLI

    # To ~/.claude/skills/moltsets-cli/
    moltsets skill install

    # Or anywhere else
    moltsets skill install --dir ./skills


Path 5: Use an integration partner

Who this is for

Teams who already work in a GTM, automation, or AI agent platform and want MoltSets data to show up there. That includes enrichment tables like Clay, Databar, and Apify, AI agent workspaces like Oxygen, Dench, and Hubi AI, and agent toolkits like Composio. This is the quickest path if your workflow already lives in another tool and you’d rather add MoltSets to it than learn something new.

Use case

You’re building a list, running enrichment in a table, or setting up an agent in a partner’s platform, and want MoltSets as one of the steps. Verified business emails, mobile phones, profiles, and company data come back into the same table, workflow, or chat, alongside your other sources.

Before you start

What you need depends on the partner. Most ask you to connect your MoltSets account or paste your API key (keys start with ms_), and those lookups run on your MoltSets plan, the same as calling MoltSets yourself. A few partners, such as Magister, include MoltSets data in their own service and bill you directly, so you don’t need a MoltSets account. Each listing on our integrations page shows which billing model it uses and links to the partner’s setup steps.

Integration partners

See our integrations page for an up-to-date list of MoltSets integration partners.


Example Prompts

Once connected, you can talk to MoltSets the same way you'd talk to a colleague. Here are a few prompts to get started:

Enrich a contact from LinkedIn

"Enrich this LinkedIn profile and give me their business email and phone number: linkedin.com/in/example"

Look up a visitor

"I have an IP address from a site visitor — 192.0.2.1 — can you tell me who this is?"

Resolve a hashed email

"Resolve this HEM to a real identity and return the name and company: abc123..."

Bulk enrich a list

"Here are 10 LinkedIn URLs. Enrich each one for business email and return the results as a table."


Reading an Outcome

Every MoltSets tool call ends in one of three outcomes, and Claude should tell them apart before it reports back to you:

Outcome

MCP response

What it means

Found

isError: false, status: "ok"

Data was found and returned. Tokens charged.

Not found

isError: false, status: "not_found"

The tool ran fine; MoltSets holds no data for that input. Nothing charged.

Error

isError: true with an error code

The call did not complete — bad input, no tokens, plan restriction, rate limit, or an outage.

A not-found is a normal, uncharged result, not a failure — the lookup was clean, the data simply isn't on file. It still counts as one request against your Fair Use requests limit.

When it really is an error

Code

Means

Next step

invalid_input

A parameter is wrong

Fix the parameter — rerunning it unchanged repeats the error

insufficient_tokens

Out of tokens

Top up or upgrade; get_billing shows the balance

insufficient_phone_tokens

Out of phone tokens

A separate allowance from regular tokens

plan_restricted

The tool isn't on your plan

A plan condition, not a data miss — switch tools or contact support

fair_use_limit_exceeded / fair_use_requests_exceeded

A Fair Use window is exhausted

Wait the number of seconds in metadata.retry_after, then resume

rate_limited

Too many calls too quickly

Back off briefly

unauthorized / account_inactive

Credentials or account problem

Recheck the connector; contact support if the account is inactive

tool_not_found

Unknown or retired tool name

Check the name against the tool list

internal_error

The endpoint is temporarily offline

Stop retrying that tool for now; nothing is charged and the team is alerted automatically

Nothing is charged on an error.

Did this answer your question?