Get API key

MCP guide

Connect LookValid to Cursor

Cursor reads MCP servers from a JSON file. Add LookValid there to run phone, email, IP, domain and website lookups from the chat, with the key kept out of the file.

Server addresses

UseAddress
Free tools, or every tool with a keyhttps://YOUR_API_HOST/v1/mcp
Browser sign-in (OAuth)https://YOUR_API_HOST/v1/mcp/oauth

The free tools need no key: 25 lookups per day and 5 per 60 seconds from one address, shared with the free tools on the website. Everything else needs an API key or a sign-in.

Set it up in four steps

1. Create a key and set it in your environment

Create an API key in the dashboard and export it as LOOKVALID_API_KEY in the shell that starts Cursor. Skip this step to use only the free tools, which need no key.

Shell

Terminal
export LOOKVALID_API_KEY="your key"

2. Add the server to mcp.json

Put this in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json to use it in every project. Cursor expands the ${env:NAME} syntax from your environment, so the key is not written to the file.

With an API key

.cursor/mcp.json
{
  "mcpServers": {
    "lookvalid": {
      "url": "https://YOUR_API_HOST/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LOOKVALID_API_KEY}"
      }
    }
  }
}

3. Or sign in with your browser

Cursor supports OAuth for remote servers. Use the sign-in address as the url and leave out the headers. Cursor registers itself, opens https://lookvalid.com/oauth/authorize in your browser, and you approve it.

With sign-in (OAuth)

.cursor/mcp.json
{
  "mcpServers": {
    "lookvalid": {
      "url": "https://YOUR_API_HOST/v1/mcp/oauth"
    }
  }
}

4. Restart and ask

Reload Cursor so it reads the file, then open the chat and ask for a lookup. Cursor lists the tools it found for the server in its MCP settings.

Tools the server advertises

ToolProductNeeds a key or sign-in
phonePhone Numbering-Plan ValidationNo, free tool
country_codeCountry Calling CodesNo, free tool
email_domain_checkEmail Domain CheckNo, free tool
ipIP IntelligenceNo, free tool
phone_spamPhone Spam CheckNo, free tool
link_safetyLink Safety CheckNo, free tool
carrier_lookupCarrier Lookup (original carrier)No, free tool
vin_decoderVIN DecoderNo, free tool
link_in_bio_lookupLink-in-Bio LookupNo, free tool
domain_authorityDomain AuthorityNo, free tool
domain_ageDomain AgeNo, free tool
website_contacts_scraperWebsite Contacts ScraperNo, free tool
site_filesSite Files CheckerNo, free tool
website_scraperWebsite ScraperYes
get_accountAccount balance and keysYes

Without a key the server lists only the free tools. Prices are on the pricing page.

Prompts to try

  • Where is the IP address 8.8.8.8 located, and does it belong to a hosting provider?
  • Check the email setup of example.com: does it have mail servers, SPF and DMARC?
  • How old is the domain example.com and who is its registrar?
  • Decode this VIN and tell me the make, model and model year: 1HGCM82633A004352.
  • Is the number +12025550143 formatted correctly, and what type of number does its numbering plan give it?
  • What is my LookValid credit balance?

Troubleshooting

HTTP 401, or the server shows as failed in the client

The key is missing, mistyped or revoked, or you connected to the sign-in address (https://YOUR_API_HOST/v1/mcp/oauth) without signing in. That address always answers 401 until a sign-in finishes. A wrong key is never quietly downgraded to the free tools.

Check that Cursor sends "Authorization: Bearer <key>" with a live key from the dashboard, or finish the browser sign-in. To use only the free tools, connect to https://YOUR_API_HOST/v1/mcp with no header.

HTTP 429 or a rate_limited tool error

Without a key, the free tools allow 25 lookups per day and 5 per 60 seconds from one address, shared with the free tools on the website. A key has its own per-key limit.

Wait for the number of seconds in the error, which is also sent as a Retry-After header, or add a key. Listing the tools never uses the allowance.

HTTP 503 or a provider_unavailable tool error

The data behind that lookup is not available to the server right now. Nothing was charged.

Retry later, or try another tool. The error body says whether it is retryable.

A tool error says the connection was not given a permission

You signed in but unticked "Run lookups" or "Read your balance and keys" on the approval page.

Disconnect the app under Connected apps in the dashboard (https://lookvalid.com/dashboard/apps), then connect again and approve both permissions.

Every error follows the standard error format.

Questions

Why is my key not picked up?

Cursor resolves ${env:LOOKVALID_API_KEY} from the environment of the process that started it. Export the variable before you launch Cursor, or restart Cursor from a shell where it is set.

Can I use the free tools without a key in Cursor?

Yes. Remove the headers and set the url to https://YOUR_API_HOST/v1/mcp. The free tools (phone, country_code, email_domain_check, ip, phone_spam, link_safety, carrier_lookup, vin_decoder, link_in_bio_lookup, domain_authority, domain_age, website_contacts_scraper, site_files) answer with no key, limited to 25 lookups per day and 5 per 60 seconds from one address.

Which file should I edit, project or global?

Use .cursor/mcp.json for one project and ~/.cursor/mcp.json for every project. Do not commit a file that holds a pasted key; the environment variable form avoids that.

Does it cost credits?

Lookups with a key or a sign-in spend credits from the same balance as the REST API, only when a lookup finds something. Repeating a lookup within the cache window is free. The free tools are never billed.

Sources

LookValid is run by Meralume Labs. It is not connected to, endorsed by or a partner of any company or product named on this page, and every product name belongs to its owner.

LookValid puts every lookup behind one key and one credit balance, over REST and MCP.

Read the quickstart