MoltSets MCP Server

Legacy enrichment tools are form-based and manual. MoltSets is prompt-and-go. It’s an MCP built specifically for AI agents — so your agent can de-anonymize website visitors, resolve contacts to hashed emails (HEMs) for ad audiences, enrich contacts from LinkedIn, and connect the dots between IP addresses, MAIDs, and people. The full identity graph, accessible in a single tool call.

What is the MoltSets MCP Server?

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect directly to external tools and data sources instead of relying on their training data. The MoltSets MCP Server gives any compatible AI tool direct access to MoltSets enrichment capabilities — every endpoint, parameter, and response schema — so your agent can enrich contacts, resolve identities, and look up visitor data without leaving the conversation. MCP Server URL

https://mcp.moltsets.com/mcp

Why Use It?

AI models are trained on static snapshots of the internet. When they generate code for an API, they often:

Hallucinate endpoints that don’t exist
Use outdated parameter names
Return incorrect response shapes

With the MoltSets MCP Server connected:

Without MCP	With MCP
AI guesses endpoint URLs	AI reads the real API reference
Outdated parameter names	Always up-to-date parameter schemas
Incorrect response shapes	Accurate response structures from source
Back-and-forth corrections	Correct code on the first try

Setup

Pick your client — each guide is a short, self-contained walkthrough.

Claude.ai

Add the connector on a personal plan, or roll it out across a Team or Enterprise org.

Claude Desktop

Same connectors as your Claude account, plus bulk tool-permission settings.

Claude Code

One claude mcp add command, at project or user scope, authorized over OAuth.

ChatGPT

Add MoltSets as a custom connector — Plus, Team, or Enterprise, OAuth only.

Grok

Bring Your Own MCP at grok.com/connectors — paid accounts, any tier.

Cursor

Add it from Cursor Settings or .cursor/mcp.json, authorized over OAuth.

Windsurf

Add it in Cascade → MCP Servers over HTTP/Streamable.

Other MCP clients

Any client that supports remote HTTP servers — loopback redirect URIs and PKCE.

To get your credentials, log into app.moltsets.com and go to Connectors to create a new connector.

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?”

Build ad-audience match keys

“Get the SHA256 hashed emails for linkedin.com/in/example so I can upload them to a Meta custom audience”

Bulk enrich a list

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

Visit “I Have X, I Want Y” for more example prompts.

Reading an outcome

Every MoltSets tool call ends in one of three outcomes, and the agent 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 for that input. It still consumes one request against your Fair Use requests limit. An agent should say “no email on file for that profile” and move on — or try a neighbouring tool — rather than reporting that the API errored. Where to go next after a miss:

Missed on	Try next
`linkedin_to_business_email`	`linkedin_to_best_email`, then `linkedin_to_personal_email_usa` (US records only, where your plan allows)
`linkedin_to_best_email`	`reverse_linkedin_lookup` for the wider profile
`search_business_email_by_name`	`search_linkedin_profile` to confirm the person exists, then enrich
`email_to_linkedin`	`reverse_email_lookup` for the profile without the URL
`ip_to_company`	Nothing — consumer ISP traffic often has no company behind it

When it really is an error

A genuine error comes back with isError: true and an error.code. What the agent should do next depends on the code:

Code	Means	Next step
`invalid_input`	A parameter is wrong	Fix the parameter — rerunning it unchanged repeats the error
`forbidden`	The connection is missing a `User-Agent` header	Set a `User-Agent` on the client — any non-empty value works
`insufficient_tokens`	Out of tokens	Top up or upgrade; `get_billing` shows the balance
`insufficient_phone_tokens`	Out of phone tokens	Phone tokens come from a separate monthly subscription
`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 `metadata.retry_after` seconds, then resume
`rate_limited`	Too many calls too quickly	Back off briefly
`search_concurrency_exceeded`	Too many searches running at once	Wait 1 second, then retry with fewer `search_people` / `search_companies` calls in parallel
`unauthorized` / `account_inactive`	Credentials or account problem	Recheck the connector; if the account is inactive, log in at app.moltsets.com and subscribe to a plan
`tool_not_found`	Unknown or retired tool name	Check the name against `tools/list`
`internal_error`	The call couldn’t complete	Retry with a smaller request; if that fails too, stop retrying that tool and come back later

Nothing is charged on an error. The full table with REST status codes is in Errors.

Over REST the same three outcomes map to HTTP status this way: found and not-found are both 200 (read status in the body to tell them apart), and errors are 4xx/5xx. See Reading an outcome.

Tokens & Costs

You only spend tokens on verified data that is actually returned. A few rules the agent follows automatically:

No data, no charge. Calls that come back with status: "not_found" cost nothing — a miss is a normal outcome, not an error.
Counting is free. search_linkedin_profile with count_only: true returns match counts without spending tokens — use it to size a search before committing.
Free tools. get_account, get_billing, and get_usage never cost tokens. Call get_billing for the per-tool token_costs map and your current balance.
Phone tokens are separate. linkedin_to_mobile_phone spends phone tokens at 1 per returned result. Phone tokens are separate from your regular token balance and come from a monthly phone token subscription, available on paid plans only.

For a full breakdown, see the Rate Limits guide.

New to the API? Start with Authentication to create your keys, then browse the API Reference Overview for every endpoint, parameter, and response schema the MCP exposes.

Troubleshooting

Connection fails after adding the config

Restart your AI tool after adding the MCP configuration. Most clients need a full restart to detect new MCP servers.Verify the URL is exactly:

https://mcp.moltsets.com/mcp

No trailing slash, no extra path segments.

The authorization request is rejected (invalid redirect URI)

Terminal clients must call back to a loopback address — 127.0.0.1, localhost, or [::1]. A plain http callback on any other host is refused; everything else must use https.If your callback is loopback and it is still refused, check that the client sends a PKCE code_challenge (method S256) — it is required for loopback — and that the callback path matches the one registered for your connector. The port is allowed to change between runs; the path is not.Full rules are on the Authentication page.

Connection rejected with forbidden / 403

MoltSets requires a User-Agent header on every connection, MCP included. A 403 with error.code: "forbidden" means the request didn’t include one.Any non-empty value is accepted — MoltSets doesn’t check its contents. Most MCP clients send a User-Agent automatically; if you built a custom client or it lets you send bare requests, configure it to set one explicitly. See User-Agent header.

Authentication errors (invalid credentials)

Double-check that your Client ID and Client Secret are copied correctly from app.moltsets.com — no extra spaces, no truncation.If your credentials were recently rotated or revoked, generate a new connector from the Connectors page and update your config with the new values. Then restart your AI tool.

Network or timeout errors

Check your network connection and try again. If the issue persists, verify the server is reachable by opening https://mcp.moltsets.com/mcp in your browser. If you see a response (even an error page), the server is up and the issue is likely local to your config.

internal_error / 500 responses

A 500 with internal_error means the call couldn’t complete. Usually the endpoint is temporarily offline, but an unusually large or heavy request can also fail this way:

{
  "error": {
    "code": "internal_error",
    "message": "Unexpected connection error."
  },
  "metadata": {}
}

Have your agent try a smaller request first — for example, split a batch into smaller batches. If that works, keep the smaller size. The MoltSets team is alerted automatically, so there’s no need to report it.If a smaller request fails too, the endpoint is temporarily offline. Resolution time varies with when the outage starts — an outage during office hours is picked up sooner than one overnight or over a weekend — so there’s no useful fixed wait. Have your agent stop retrying that tool, work on something else, and come back to it later in the session or in a follow-up run.

Switching from linkedin_to_personal_email to _usa

The personal-email tools were previously named linkedin_to_personal_email and linkedin_to_best_personal_email. To migrate, add _usa to the end of the tool or route name — same data, same format, with non-US records now filtered out. The old names still work for now but will be retired in the near future — switch to the _usa names before then.

plan_restricted on a personal email lookup

linkedin_to_personal_email_usa and linkedin_to_best_personal_email_usa are not available on every plan — access is set by price tier. Call get_account and read personal_email_available to know where yours stands. Calls from an account without access return 403:

{
  "error": {
    "code": "plan_restricted",
    "message": "Personal email lookups are not available on your plan. Contact support@moltsets.com to request access."
  }
}

This is an account entitlement, not a data miss — retrying or rewording the prompt won’t help. (Separately, both tools return US records only — a non-US profile is a not_found, not a plan_restricted.) Use linkedin_to_business_email instead, or contact support@moltsets.com to request access.

plan_restricted on an ad audience lookup

email_to_maid, business_email_to_sha256, and linkedin_to_sha256 are not available on the $397 / month and $997 / month plans. Calls from those plans return 403 with plan_restricted.This is an account entitlement, not a data miss — retrying or rewording the prompt won’t help.

The agent reports an error when the lookup simply found nothing

Check the status field on the response. A clean miss comes back as a success — isError: false with status: "not_found" — and costs nothing. It is not an error, and retrying the same input will return the same miss.Older integrations saw a 404 for this case. That is no longer sent: over REST both a hit and a miss return 200, and the body’s status tells them apart. If an agent is relaying misses as API failures, tell it to read status before reporting, and to try the next tool in the chain above.

Getting Started

MoltSets' Data

Use Cases

Best Practices

Integrations

What is the MoltSets MCP Server?

Why Use It?

Setup

Claude.ai

Claude Desktop

Claude Code

ChatGPT

Grok

Cursor

Windsurf

Other MCP clients

Example Prompts

Reading an outcome

When it really is an error

Tokens & Costs

Troubleshooting

​What is the MoltSets MCP Server?

​Why Use It?

​Setup

Claude.ai

Claude Desktop

Claude Code

ChatGPT

Grok

Cursor

Windsurf

Other MCP clients

​Example Prompts

​Reading an outcome

​When it really is an error

​Tokens & Costs

​Troubleshooting

What is the MoltSets MCP Server?

Why Use It?

Setup

Example Prompts

Reading an outcome

When it really is an error

Tokens & Costs

Troubleshooting