MCP server

LookValid is a Model Context Protocol server, so an AI assistant can run lookups directly. Every product is a tool, billed at the same credit prices as the REST API, from the same balance. The free tools also work without a key (see below); everything else needs a key.

Connection details

Get a key by emailing hello@lookvalid.com. The reply carries your key and the server address, which the URLs and snippets on this page show as YOUR_API_HOST. Keep the key in an environment variable named LOOKVALID_API_KEY. Most snippets below read it from that variable. The Claude Desktop snippet and add-mcp write the key into the client's config file, so keep that file private.

Sign in with OAuth

Clients that open your browser to sign you in do not need a key at all. LookValid follows the MCP authorization specification: OAuth 2.1 authorization code flow with PKCE (S256 only), dynamic client registration and refresh tokens.

Connect to this address instead of the one above:

It is the same server, with the same tools and prices, but it asks for a sign-in: a request with no credentials is answered with HTTP 401 and a WWW-Authenticate header that points the client at /.well-known/oauth-protected-resource. The plain address above keeps serving the free tools to a caller with no credentials, so it never starts a sign-in on its own.

In Claude Code, add the server without a header, then run /mcp and choose LookValid to sign in:

claude mcp add --transport http lookvalid https://YOUR_API_HOST/v1/mcp/oauth

Cursor, VS Code and other clients that support OAuth need only the URL in their server entry, with no headers. The client registers itself, opens https://lookvalid.com/oauth/authorize in your browser, and you sign in with your LookValid account.

What you approve:

• Run lookups lets the app run lookups as your account. Credits are spent the same way as with a key: only when a lookup finds something, and nothing for an invalid, refused or failed one.
• Read your balance and keys lets it call get_account, which lists key ids and prefixes, never the keys.

You can untick a permission before you allow. An app without lookup sees only get_account.

How it behaves:

• An access token lasts 1 hour. The client refreshes it with a refresh token that rotates on every use. If a refresh token is ever used twice, LookValid treats it as stolen and ends the connection.
• A token opens the MCP server only. It does not work on the REST API; use an API key there.
• Disconnect any app under Connected apps in the dashboard. Its access stops on the next request.
• Redirect addresses must be https, or http on 127.0.0.1, [::1] or localhost. A client that returns to a custom scheme such as myapp:// is refused at registration; use an API key with it.

Endpoints, for a client you are writing: https://YOUR_API_HOST/.well-known/oauth-protected-resource, https://YOUR_API_HOST/.well-known/oauth-authorization-server, POST https://YOUR_API_HOST/oauth/register, POST https://YOUR_API_HOST/oauth/token and POST https://YOUR_API_HOST/oauth/revoke. Scopes are lookup and account:read.

Claude

Claude Code:

claude mcp add --transport http lookvalid https://YOUR_API_HOST/v1/mcp --header "Authorization: Bearer $LOOKVALID_API_KEY"

Claude Desktop connects to remote servers with header authentication through the mcp-remote bridge. Add this to claude_desktop_config.json and put your key in env:

1{
2  "mcpServers": {
3    "lookvalid": {
4      "command": "npx",
5      "args": ["-y", "mcp-remote", "https://YOUR_API_HOST/v1/mcp", "--header", "Authorization:${LOOKVALID_AUTH}"],
6      "env": { "LOOKVALID_AUTH": "Bearer lv_live_..." }
7    }
8  }
9}

Cursor

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project. Cursor expands ${env:NAME} from your environment:

1{
2  "mcpServers": {
3    "lookvalid": {
4      "url": "https://YOUR_API_HOST/v1/mcp",
5      "headers": {
6        "Authorization": "Bearer ${env:LOOKVALID_API_KEY}"
7      }
8    }
9  }
10}

VS Code

Add the server to .vscode/mcp.json in your workspace. VS Code asks for the key once, the first time the server starts, and keeps it out of the file:

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "lookvalid-api-key",
6      "description": "LookValid API key",
7      "password": true
8    }
9  ],
10  "servers": {
11    "lookvalid": {
12      "type": "http",
13      "url": "https://YOUR_API_HOST/v1/mcp",
14      "headers": {
15        "Authorization": "Bearer ${input:lookvalid-api-key}"
16      }
17    }
18  }
19}

Codex

Add the server to ~/.codex/config.toml. Codex reads the bearer token from the environment variable you name:

[mcp_servers.lookvalid]
url = "https://YOUR_API_HOST/v1/mcp"
bearer_token_env_var = "LOOKVALID_API_KEY"

The same entry from the command line:

codex mcp add lookvalid --url https://YOUR_API_HOST/v1/mcp --bearer-token-env-var LOOKVALID_API_KEY

Any client with one command

The add-mcp package writes the server into the config of the coding agents it finds on your machine, including Claude Code, Cursor, VS Code and Codex:

npx -y add-mcp https://YOUR_API_HOST/v1/mcp --name lookvalid --header "Authorization: Bearer $LOOKVALID_API_KEY"

Your shell expands $LOOKVALID_API_KEY before add-mcp runs, so the key itself is written into each config file it touches. Use the snippets above when you want the key to stay in an environment variable.

Client configuration formats change between releases. If a snippet does not load, check your client's MCP documentation for the current field names. The URL and the bearer header are the only things LookValid needs.

Tools

Tool names are the product id with hyphens turned into underscores. Each tool takes the same input as its REST endpoint and returns the same envelope (found, data, sources, credits_charged, cache_hit).

Free tools without a key

Connect to the same URL with no Authorization header and the server offers only 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. They run the same lookups as the free tools and the free HTTP endpoint (POST https://YOUR_API_HOST/v1/public/tools/<product>), need no account, and are never billed or cached against a balance.

• Limits. By default 25 lookups per day and 5 per 60 seconds from one address. MCP and the free HTTP endpoint share that one allowance, so using both does not give you more. Listing the tools costs nothing. When a limit is reached the tool call returns a rate_limited error with the number of seconds to wait.
• website_contacts_scraper crawls at most 3 pages without a key.
• Everything else needs a key. Calling any other tool, or get_account, without a key returns an unauthorized tool error that names the free tools. Nothing runs and nothing is charged. A key that is wrong gets HTTP 401; it is never quietly downgraded to the free tools.
• When to add a key. The free tools suit trying a lookup. For more volume, the other products, your balance and your own limits, create a key and send it as a bearer token.

Billing and errors

Tool calls with a key bill and cache exactly like the REST routes: success billing where the product uses it, free repeats for 7 days, and no charge on errors. A failed tool call returns the standard error envelope with isError set.

Try it from the command line

List the free tools, no key needed:

curl -X POST https://YOUR_API_HOST/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

List every tool with your key:

curl -X POST https://YOUR_API_HOST/v1/mcp \
  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'