Connect Claude to a lookup API over MCP

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 ¹. 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 ¹. 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.

Pick the client you use. In Claude Code, one command registers the server and stores the header with it:

1claude 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:

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}

Codex reads the bearer token from the same variable. Put this in ~/.codex/config.toml:

1[mcp_servers.lookvalid]
2url = "https://YOUR_API_HOST/v1/mcp"
3bearer_token_env_var = "LOOKVALID_API_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.

1claude 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. The client uses PKCE with the S256 method, which the specification requires of clients ².
3. Tokens travel in the Authorization: Bearer header on every request and must not appear in a URL query string ².

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.

Before debugging a client, send the protocol message it would send. This lists every tool your key can use:

1curl -X POST https://YOUR_API_HOST/v1/mcp \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -H "Accept: application/json, text/event-stream" \
5  -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.

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

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, and the quickstart covers the same lookups over plain REST.