--- title: "Connect LookValid to Cursor over MCP" url: "https://lookvalid.com/mcp/cursor.md" canonical_url: "https://lookvalid.com/mcp/cursor" last_updated: "2026-10-22" type: "how-to" summary: "Add the LookValid MCP server to Cursor in .cursor/mcp.json, keep your key in an environment variable, and run lookups from the chat." related: ["https://lookvalid.com/mcp/oauth.md", "https://lookvalid.com/mcp/claude.md", "https://lookvalid.com/docs/mcp.md"] --- # Connect LookValid to Cursor over MCP Add the LookValid MCP server to Cursor in .cursor/mcp.json, keep your key in an environment variable, and run lookups from the chat. 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 | Use | Address | | --- | --- | | Free tools, or every tool with a key | `https://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: ```bash 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: ```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): ```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 | Tool | Product | Needs a key or sign-in | | --- | --- | --- | | `phone` | Phone Numbering-Plan Validation | No, free tool | | `country_code` | Country Calling Codes | No, free tool | | `email_domain_check` | Email Domain Check | No, free tool | | `ip` | IP Intelligence | No, free tool | | `phone_spam` | Phone Spam Check | No, free tool | | `link_safety` | Link Safety Check | No, free tool | | `carrier_lookup` | Carrier Lookup (original carrier) | No, free tool | | `vin_decoder` | VIN Decoder | No, free tool | | `link_in_bio_lookup` | Link-in-Bio Lookup | No, free tool | | `domain_authority` | Domain Authority | No, free tool | | `domain_age` | Domain Age | No, free tool | | `website_contacts_scraper` | Website Contacts Scraper | No, free tool | | `site_files` | Site Files Checker | No, free tool | | `website_scraper` | Website Scraper | Yes | | `get_account` | Account balance and keys | Yes | Without a key the server lists only the free tools. ## 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 " 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. ## 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 - [Cursor documentation: Model Context Protocol](https://cursor.com/docs/context/mcp), read 2026-10-18 - [Model Context Protocol specification: Authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), read 2026-10-18 ## Related - [MCP sign-in with OAuth for LookValid](https://lookvalid.com/mcp/oauth.md) - [Connect LookValid to Claude over MCP](https://lookvalid.com/mcp/claude.md) - [MCP server](https://lookvalid.com/docs/mcp.md)