--- title: "MCP sign-in with OAuth for LookValid" url: "https://lookvalid.com/mcp/oauth.md" canonical_url: "https://lookvalid.com/mcp/oauth" last_updated: "2026-10-22" type: "how-to" summary: "How a client signs in to the LookValid MCP server with OAuth: one address, a browser approval, one-hour tokens, and how to disconnect an app." related: ["https://lookvalid.com/mcp/claude.md", "https://lookvalid.com/mcp/cursor.md", "https://lookvalid.com/docs/mcp.md"] --- # MCP sign-in with OAuth for LookValid How a client signs in to the LookValid MCP server with OAuth: one address, a browser approval, one-hour tokens, and how to disconnect an app. Clients that support OAuth can connect to LookValid without a stored key. You sign in once in your browser, approve what the app may do, and the client keeps short-lived tokens. ## 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. Connect to the sign-in address Use https://YOUR_API_HOST/v1/mcp/oauth as the server address, with no Authorization header. It is the same server, tools and prices as https://YOUR_API_HOST/v1/mcp, but a request with no credentials is answered with HTTP 401 and a WWW-Authenticate header that points the client at the server's metadata. The plain address keeps serving the free tools with no sign-in, so it never starts a sign-in by itself. Claude Code: ```bash claude mcp add --transport http lookvalid https://YOUR_API_HOST/v1/mcp/oauth ``` ### 2. The client finds and registers itself The client reads https://YOUR_API_HOST/.well-known/oauth-protected-resource, then https://YOUR_API_HOST/.well-known/oauth-authorization-server, and registers itself with dynamic client registration. Redirect addresses must be https, or http on localhost, 127.0.0.1 or [::1]. A client that returns to a custom scheme such as myapp:// is refused at registration; use an API key with it. ### 3. Approve in your browser The client opens https://lookvalid.com/oauth/authorize. Sign in to your LookValid account and choose what the app may do: "Run lookups" lets it run lookups as your account, and "Read your balance and keys" lets it call get_account, which lists key ids and prefixes and never the keys themselves. You can untick either before you allow. The flow is the authorization code grant with PKCE, and only the S256 method is accepted. ### 4. Use it, and disconnect when you like An access token lasts one hour. The client renews it with a refresh token that is replaced every time it is used, and if a refresh token is ever used twice the connection ends. A token opens the MCP server only and does not work on the REST API. To disconnect an app, open Connected apps in the dashboard; its access stops on the next request. ## 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 your client 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 ### What can a connected app do with my account? Only what you ticked on the approval page: run lookups (which spend your credits the way a key does) and read your balance and the list of key ids. It cannot read a key, change billing or call the REST API. ### Why are there two MCP addresses? https://YOUR_API_HOST/v1/mcp serves the free tools to anyone and the full tool set to a key, so a client that connects there is never told to sign in. https://YOUR_API_HOST/v1/mcp/oauth answers 401 until a sign-in finishes, which is what makes an OAuth client start the flow. ### How long does a sign-in last? The access token lasts one hour and the client refreshes it automatically. If the refresh token stops working or you disconnect the app, the client asks you to sign in again. ### My client does not support OAuth. What now? Use an API key as a bearer token. The Claude and Cursor guides show the exact setup, and the MCP docs page covers VS Code, Codex and others. ## Sources - [Model Context Protocol specification: Authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), read 2026-10-18 - [Claude Code documentation: Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp), read 2026-10-18 - [Cursor documentation: Model Context Protocol](https://cursor.com/docs/context/mcp), read 2026-10-18 ## Related - [Connect LookValid to Claude over MCP](https://lookvalid.com/mcp/claude.md) - [Connect LookValid to Cursor over MCP](https://lookvalid.com/mcp/cursor.md) - [MCP server](https://lookvalid.com/docs/mcp.md)