# fieldlookup

> Bounded public business and community data tools for AI agents over streamable HTTP MCP.

- Website: https://fieldlookup.com/
- Reddit search setup for Grok Bot: https://fieldlookup.com/grok/reddit
- MCP endpoint (streamable HTTP): https://fieldlookup.com/mcp
- Free access for personal and business use (50 calls/UTC month, no card, Turnstile verification): https://fieldlookup.com/free
- Documentation: https://fieldlookup.com/docs
- Pricing and paid Checkout: https://fieldlookup.com/#pricing
- Account sign-in, credit and recovery: https://fieldlookup.com/account
- OAuth 2.1 Protected Resource metadata: https://fieldlookup.com/.well-known/oauth-protected-resource/mcp
- OAuth 2.1 Authorization Server metadata: https://fieldlookup.com/.well-known/oauth-authorization-server
- Support: mailto:support@fieldlookup.com (https://fieldlookup.com/support)
- Legal: https://fieldlookup.com/terms | https://fieldlookup.com/privacy | https://fieldlookup.com/imprint

## Connection and operational rules

- Send `Authorization: Bearer YOUR_API_KEY` on `tools/call` requests to `https://fieldlookup.com/mcp`.
- OAuth 2.1 clients can authorize with authorization code + S256 PKCE (`scope`: `tools:call`). At consent choose "Connect free" for a new account or "Reconnect free" for an existing Free account. No card, password, business declaration or checkbox is needed; that click accepts the Terms. An existing API key can also be used.
- Apps without OAuth: `POST https://fieldlookup.com/free/link` returns `device_code`, `user_code` and `verification_uri_complete`. Show the user the URL and code; they approve in a browser. Poll `POST https://fieldlookup.com/free/link/token` with `{"device_code": "..."}` every 5 seconds: `authorization_pending` until approval, then `api_key` once. Codes expire after 10 minutes.
- `initialize`, `tools/list` and `/health` require no key and consume zero quota.
- Long searches: a call still running after 45 seconds returns `{"status": "running", "job_id": "..."}`. Call `get_result` with that `job_id`; each call waits up to 45 seconds and returns the records when ready. Searches end after 100 seconds and results stay collectable for at least 170 seconds after that. No client tool timeout above 60 seconds is needed.
- Rate and concurrency limits: at most 2 concurrent calls and 30 call attempts per rolling 60 seconds per customer.
- Billing and quota behavior: each delivered search counts as 1 call (including 0-match searches). `get_result` and identical repeat calls while a search runs consume nothing extra. Failed, canceled and never-collected searches release their reservation without consuming quota.
- Never ask users to paste live API keys into third-party chat logs when a local MCP client config or secret environment variable can be configured directly.

## Plans (USD, exclusive of applicable VAT)

- Free: USD 0/month, 50 included calls. Overage: No automatic overage; prepaid credit can extend the allowance.
- Starter: USD 19/month, 500 included calls. Overage: Optional USD 0.05/call up to chosen cap (0 to 5,000, default 0).
- Pro: USD 49/month, 2,000 included calls. Overage: Optional USD 0.05/call up to chosen cap (0 to 5,000, default 0).

## Tools

### `find_businesses`
Find businesses by category and location, with addresses, websites, phone numbers and ratings. A search still running after 45 seconds returns status running and a job_id; call get_result to collect it.
- Return shape: `{"records": [...], "count": number}` with compact fields: `name, website, phone, address, latitude, longitude, rating` (unavailable values are `null`).
- Parameter `query` (required): `{"maxLength": 200, "minLength": 1, "type": "string"}`
- Parameter `max_results` (optional, default 10): `{"maximum": 25, "minimum": 1, "type": "integer"}`
- Parameter `location` (required): `{"maxLength": 200, "minLength": 1, "type": "string"}`

### `find_shopify_stores`
Find Shopify stores by product niche and country served, with websites and available business contacts. A search still running after 45 seconds returns status running and a job_id; call get_result to collect it.
- Return shape: `{"records": [...], "count": number}` with compact fields: `name, website, domain, email, phone, city, country, rating` (unavailable values are `null`).
- Parameter `query` (required): `{"maxLength": 200, "minLength": 1, "type": "string"}`
- Parameter `max_results` (optional, default 10): `{"maximum": 25, "minimum": 1, "type": "integer"}`
- Parameter `country` (optional, default ""): `{"enum": ["", "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "IT", "ES", "NL", "PL", "AT", "CH", "PT", "SE", "DK", "FI"], "type": "string"}`

### `find_suppliers`
Find industrial suppliers by product, material or service, with company descriptions and business contacts. A search still running after 45 seconds returns status running and a job_id; call get_result to collect it.
- Return shape: `{"records": [...], "count": number}` with compact fields: `name, website, phone, description, city, region, country` (unavailable values are `null`).
- Parameter `query` (required): `{"maxLength": 200, "minLength": 1, "type": "string"}`
- Parameter `max_results` (optional, default 10): `{"maximum": 25, "minimum": 1, "type": "integer"}`

### `search_reddit`
Search Reddit posts or comments by keywords, with text excerpts, links and scores. Use quotes for an exact phrase, for example "app pricing"; unquoted words may match separate parts of a post. Use subreddit without r/. Sort new prioritizes recency; relevance prioritizes matching. text_truncated means the excerpt omits part of the text. A limited sample does not establish that other relevant discussions are absent. A search still running after 45 seconds returns status running and a job_id; call get_result to collect it.
- Return shape: `{"records": [...], "count": number}` with compact fields: `title, text, url, text_truncated, subreddit, author, score, created_at, type` (unavailable values are `null`).
- Parameter `query` (required): `{"maxLength": 200, "minLength": 1, "type": "string"}`
- Parameter `max_results` (optional, default 10): `{"maximum": 25, "minimum": 1, "type": "integer"}`
- Parameter `subreddit` (optional, default ""): `{"pattern": "^[A-Za-z0-9_]{0,30}$", "type": "string"}`
- Parameter `sort` (optional, default "relevance"): `{"enum": ["relevance", "new", "top"], "type": "string"}`
- Parameter `content_type` (optional, default "posts"): `{"enum": ["posts", "comments"], "type": "string"}`

### `get_result`
Collect the records of a search that returned status running. Waits up to 45 seconds; call again while it still reports running. Consumes no extra call.
- Parameter `job_id` (required): the `job_id` from that response. Returns the search result shape, or status running again.

### `account_status`
Check remaining included searches, prepaid credit and current search price. Free to call, including when search allowance is exhausted. Amounts are USD cents. Credit never expires.
{"additionalProperties": false, "properties": {}, "type": "object"}

### `start_topup`
Prepare a $5, $10 or $25 non-expiring credit purchase for the currently connected account. This does not charge a card. Ask the user to open checkout_url and complete payment; do not buy without their permission. No new connection or key is needed. Free to call.
{"additionalProperties": false, "properties": {"amount_dollars": {"enum": [5, 10, 25], "type": "integer"}}, "required": ["amount_dollars"], "type": "object"}

### `checkout_status`
Check whether a credit purchase for this connection has been confirmed. Free to call. After status paid, retry the original search through this same connection.
{"additionalProperties": false, "properties": {"checkout_id": {"type": "string"}}, "required": ["checkout_id"], "type": "object"}

Prepaid: USD 5, 10 or 25 of non-expiring credit, currently USD 0.05/search. Use account_status, then start_topup, then checkout_status. Verify email at the first purchase. Payment credits the existing connection. Included allowance is used before credit; credit is used before any opted-in subscription overage. Never infer purchase permission from a stored card.