--- title: "Connect Claude to a lookup API over MCP" url: "https://lookvalid.com/blog/tutorial/connect-lookvalid-to-claude-over-mcp.md" canonical_url: "https://lookvalid.com/blog/tutorial/connect-lookvalid-to-claude-over-mcp" last_updated: "2026-10-22" type: "how-to" summary: "Add the LookValid MCP server to Claude Code, Cursor, VS Code or Codex with a key or OAuth, then test it from a terminal with one curl call." related: ["https://lookvalid.com/docs/mcp.md", "https://lookvalid.com/docs/quickstart.md", "https://lookvalid.com/glossary/mcp.md", "https://lookvalid.com/tools/ip-address-lookup.md"] --- # Connect Claude to a lookup API over MCP Add the LookValid MCP server to Claude Code, Cursor, VS Code or Codex with a key or OAuth, then test it from a terminal with one curl call. An MCP server lets an AI assistant call lookups as tools instead of you pasting results into a chat. This walkthrough adds the LookValid server to a client, shows the two ways to authenticate, and ends with a terminal check that proves the connection works. Every command below is generated from the same config file the docs use, so it matches the live server. ## What the client connects to The server lives at a single address, `https://YOUR_API_HOST/v1/mcp`. The MCP specification defines this shape for its Streamable HTTP transport: one HTTP endpoint that accepts POST requests, each carrying one JSON-RPC message [1]. The client must send an `Accept` header listing both `application/json` and `text/event-stream`, and the server answers with either a single JSON object or an event stream [1]. Your client handles all of that; you only need the address. Every live product is exposed as a tool. The tool name is the product id with hyphens turned into underscores, so `website-contacts-scraper` becomes `website_contacts_scraper`. Each tool takes the same input as its REST endpoint and returns the same envelope, and it is billed from the same credit balance. Create a key in your dashboard and keep it in an environment variable named `LOOKVALID_API_KEY`, so no key is pasted into a config file. ## Add the server to your client Pick the client you use. In Claude Code, one command registers the server and stores the header with it: Claude Code ```bash claude mcp add --transport http lookvalid https://YOUR_API_HOST/v1/mcp --header "Authorization: Bearer $LOOKVALID_API_KEY" ``` In Cursor, put this in `.cursor/mcp.json`. Cursor expands the environment variable itself, so the key stays out of the file: Cursor ```json { "mcpServers": { "lookvalid": { "url": "https://YOUR_API_HOST/v1/mcp", "headers": { "Authorization": "Bearer ${env:LOOKVALID_API_KEY}" } } } } ``` Codex reads the bearer token from the same variable. Put this in `~/.codex/config.toml`: Codex ``` [mcp_servers.lookvalid] url = "https://YOUR_API_HOST/v1/mcp" bearer_token_env_var = "LOOKVALID_API_KEY" ``` Where each snippet goes and how it finds your key | Client | Where | How the key is supplied | | --- | --- | --- | | Claude Code | A terminal command | The header is stored with the server entry | | Cursor | .cursor/mcp.json | Expanded from your environment | | VS Code | .vscode/mcp.json | A one-time password prompt, kept out of the file | | Codex | ~/.codex/config.toml | Read from LOOKVALID_API_KEY | ## Sign in with OAuth instead of a key Clients that can open a browser need no key at all. Point them at `https://YOUR_API_HOST/v1/mcp/oauth` and the server asks for a sign-in. The reason there are two addresses is that the plain address also serves the free tools to callers with no credentials, so it never starts a sign-in by itself. Claude Code with OAuth ```bash claude mcp add --transport http lookvalid https://YOUR_API_HOST/v1/mcp/oauth ``` After adding it, run `/mcp` inside Claude Code and choose the server to sign in. The flow follows the MCP authorization specification, and these parts of it are what you will see: 1. A request with no token gets HTTP 401 and a `WWW-Authenticate` header that carries a `resource_metadata` address. The client reads that document to find the authorization server [2]. 2. The client uses PKCE with the `S256` method, which the specification requires of clients [2]. 3. Tokens travel in the `Authorization: Bearer` header on every request and must not appear in a URL query string [2]. Our access tokens last one hour and are renewed with a refresh token that rotates on each use. A token opens the MCP server only, never the REST API, and you can disconnect an app from the Connected apps page in your dashboard. ## Test the connection from a terminal Before debugging a client, send the protocol message it would send. This lists every tool your key can use: List all tools with a key ```bash 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"}' ``` Drop the `Authorization` line and the same call lists only the free tools. Without a key you get 25 lookups per day and 5 per 60 seconds from one address, and the keyless website contacts tool crawls at most 3 pages. List the free tools without a key ```bash 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"}' ``` ## Fix the usual problems Symptoms and fixes when connecting | What you see | Why | What to do | | --- | --- | --- | | HTTP 401 on connect | A key was sent but it is wrong. A wrong key is never quietly treated as no key | Check the environment variable your client expands, then retry | | A tool error named unauthorized | You called a paid tool with no key | Add the header, or use the OAuth address | | A tool error named rate_limited | You passed the free per-address allowance | Wait the number of seconds the error gives, or add a key | | No tools listed | The client never completed the handshake | Run the curl call above and compare its output with what your client logs | Once the list call works, ask your assistant to check an IP address or read a company website and watch the tool call it makes. The full client list, tool table and limits are in the [MCP docs](https://lookvalid.com/docs/mcp.md), and the [quickstart](https://lookvalid.com/docs/quickstart.md) covers the same lookups over plain REST. ## Sources 1. [Model Context Protocol specification 2025-11-25: Transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), read 2026-10-19 2. [Model Context Protocol specification 2025-11-25: Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), read 2026-10-19 By LookValid engineering. Published 2026-10-19, updated 2026-10-19. ## Related - [MCP server](https://lookvalid.com/docs/mcp.md) - [Quickstart](https://lookvalid.com/docs/quickstart.md) - [What is MCP (Model Context Protocol)?](https://lookvalid.com/glossary/mcp.md) - [Free IP address lookup](https://lookvalid.com/tools/ip-address-lookup.md)