--- title: "MCP or REST: choosing how to call a lookup" url: "https://lookvalid.com/blog/technical/mcp-or-rest-for-lookups.md" canonical_url: "https://lookvalid.com/blog/technical/mcp-or-rest-for-lookups" last_updated: "2026-10-22" type: "conceptual" summary: "When a lookup should go through the MCP server and when through the REST API: who the caller is, auth, cost, determinism, batching and error handling." related: ["https://lookvalid.com/docs/mcp.md", "https://lookvalid.com/docs/quickstart.md", "https://lookvalid.com/blog/tutorial/connect-lookvalid-to-claude-over-mcp.md", "https://lookvalid.com/blog/product/free-tools-without-an-account.md"] --- # MCP or REST: choosing how to call a lookup When a lookup should go through the MCP server and when through the REST API: who the caller is, auth, cost, determinism, batching and error handling. Every live LookValid lookup is reachable two ways: as a REST endpoint and as a tool on the MCP server. They run the same lookup engine, so the data is the same; what differs is who decides to make the call and what happens around it. This post gives a rule of thumb, then compares the two on auth, cost, determinism, batching and errors. ## The short rule Use MCP when a model decides which lookup to run and with what input. Use REST when your own code decides. In the MCP specification, tools are model-controlled: the language model can discover and invoke them based on its context and the user's prompts [1]. A REST call is the opposite, because a developer wrote the request, chose the product and fixed the input. Both paths call one engine. The MCP server at `https://YOUR_API_HOST/v1/mcp` builds each tool from the same input schema as the REST route, bills the same credit balance and uses the same per-account cache. A tool is named after its product with hyphens turned into underscores, so `email-domain-check` is the tool `email_domain_check`. ## Who is the caller With MCP, the caller is an AI client such as an assistant in an editor or chat app. It lists the tools, reads their descriptions, picks one and fills in the arguments. That is useful for open questions like "is this number a known spam caller?" where you do not know in advance which lookups the answer needs. With REST, the caller is code you control: a signup handler, a CRM sync or a nightly job. The product, the input and the handling of the result are decided when you write the code, so the same input always leads to the same call. The specification says there should always be a human in the loop with the ability to deny tool invocations [1]. That is the right default for an assistant, and it is also a reason not to put MCP in a hot path that has to run without a person watching, such as a form submit. ## Auth, cost and limits The MCP endpoint accepts three kinds of caller. With an API key, every live product is available and each call is billed in credits. With OAuth, a client signs in through `https://YOUR_API_HOST/v1/mcp/oauth` and gets a token that opens MCP only, never the REST API. With neither, the server offers only the free tools under the same allowance as the keyless HTTP tools. The MCP authorization specification makes authorization optional and requires a token in the `Authorization: Bearer` header, never in the query string [2]. Keyless access is 5 lookups per 60 seconds and 25 per day from one address. The HTTP free endpoint and the keyless MCP server share that one allowance. The full explanation is in [Free lookup tools that need no account](https://lookvalid.com/blog/product/free-tools-without-an-account.md). Cost does not depend on the transport. A lookup that finds something costs the product's credits (the IP lookup costs 1 credit), a lookup that finds nothing is not charged on products with success billing, and repeating a lookup within the cache window is free. An OAuth token also carries scopes: `lookup` for running lookups and `account:read` for the `get_account` tool, which returns your balance. A token without the right scope gets a clear error and no charge. MCP and REST compared | Topic | MCP server | REST API | | --- | --- | --- | | Who decides the call | The model, with a person able to deny it | Your code | | Auth | API key, OAuth sign-in, or none for the free tools | API key | | Credits and cache | Same balance and same per-account cache | Same balance and same per-account cache | | Result shape | A tool result with the JSON as text and as structured content | The JSON body with credit headers | | Determinism | Depends on what the model chooses to call | Fixed by the code you wrote | | Large lists | Not a fit | Loop over the endpoint, or upload a CSV for a bulk job | | Failure signal | A result with isError true; auth problems as HTTP status | HTTP status plus an error body | ## Determinism and batching A REST call is deterministic in the sense that matters for software: the same request reaches the same product with the same input, and your tests can pin that down. An MCP call adds a model in front of the lookup. The lookup is still exact once called, but whether it is called, which product is chosen and how the input is phrased are the model's decisions. If an outcome must be reproducible, such as blocking a signup, call REST from code. Batching follows from the same point. Each MCP tool call is one lookup, one model step and one result in the model's context. Running ten thousand of them that way is slow and fills the context for no gain. For a list, use REST: loop over the product endpoint from your own code, or upload a CSV and let a bulk job run the rows in the background. The [bulk validation post](https://lookvalid.com/blog/technical/bulk-validation-with-csv-jobs.md) lists the limits and shows a retry loop. ## Error handling The two transports report failure differently, and your handling has to match. The MCP specification separates protocol errors, such as an unknown tool, from tool execution errors, which are normal results with `isError: true` that carry feedback the model can use to correct itself and retry [1]. LookValid returns its error envelope as that kind of result, so an assistant can read the message and fix its input. Authorization failures are different: the specification has servers answer HTTP 401 for a missing or invalid token and 403 for insufficient permissions [2]. Over REST, every failure is an HTTP status with an error body whose `docs_url` points at a page for the code. For a rate limit, HTTP defines 429 and lets the response carry a `Retry-After` header saying how long to wait [3], and the API sets that header on a rate-limited REST or MCP request. - In code, branch on the HTTP status and the error code, and back off for the number of seconds in `Retry-After`. - In an assistant, leave the model to read the `isError` result, but keep a person in the loop for calls that cost credits. - Treat `rate_limited` as retryable and `unauthorized` as a configuration problem to fix once. ## The same lookup both ways Here is one IP lookup over each transport. The body you send to REST is the same object that goes in the MCP tool arguments. REST: your code picks the product and the input ```bash curl -X POST https://YOUR_API_HOST/v1/ip \ -H "Authorization: Bearer $LOOKVALID_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ip":"8.8.8.8"}' ``` MCP: the message a client sends when a model picks the ip tool ```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/call","params":{"name":"ip","arguments":{"ip":"8.8.8.8"}}}' ``` 1. Start with MCP if you are exploring: connect an assistant with the steps in [Connect Claude to a lookup API over MCP](https://lookvalid.com/blog/tutorial/connect-lookvalid-to-claude-over-mcp.md) and ask it questions. 2. When a question turns into a repeated job, move that lookup into your code over REST so it is reproducible and testable. 3. Keep MCP for the interactive cases where you want a model to choose the lookups. The [MCP docs](https://lookvalid.com/docs/mcp.md) list every tool, and the [pricing page](https://lookvalid.com/pricing.md) shows credits per product. ## Sources 1. [Model Context Protocol specification 2025-11-25: Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), 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 3. [RFC 6585: Additional HTTP Status Codes, section 4 (429 Too Many Requests)](https://www.rfc-editor.org/rfc/rfc6585.html#section-4), 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) - [Connect Claude to a lookup API over MCP](https://lookvalid.com/blog/tutorial/connect-lookvalid-to-claude-over-mcp.md) - [Free lookup tools that need no account](https://lookvalid.com/blog/product/free-tools-without-an-account.md)