Kenso MCP tools

Place Pulls place_pulls

Bulk Google Maps place pulls: every place matching a query across whole countries or the world, read in the background, biggest cities first. estimate-place-pull is free: show the user its credits and coverage and get a yes before create-place-pull, which spends up to that (1 credit a page) and counts against the workspace's monthly bulk budget. One pull at a time: poll get-place-pull until status is not queued or running, then read list-place-pull-places (free). One area's places is search search-places. Needs search_places and places_bulk.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through place_pulls_read and changes through place_pulls_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: cancel-place-pull, create-place-pull, estimate-place-pull, get-place-pull, list-place-pull-places, list-place-pulls

cancel-place-pull

Write. Early access: needs places_bulk, search_places on for the workspace. POST https://api.ken.so/v1/search/place-pulls/{pullId}/cancel

Path: pullId

Stop a queued or running bulk place pull. It keeps the places it found. What it spent stays spent. A pull that already ended comes back unchanged.

POST /api/v1/search/place-pulls/{pull_id}/cancel. Staff, behind the search_places and
places_bulk flags. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Ends the pull as canceled;
its places stay readable with list-place-pull-places, and the workspace can start another.

Returns data: the pull, as get-place-pull returns it.

create-place-pull

Write. Early access: needs places_bulk, search_places on for the workspace. POST https://api.ken.so/v1/search/place-pulls

Body (json): countries array, hasWebsite boolean, maxPlaces integer, minRating number, minReviews integer, query string, worldwide boolean

Start a bulk Google Maps place pull. Spends credits: up to the estimate, 1 credit a page. Run estimate-place-pull first and get the user's yes on its credits. One pull runs at a time.

POST /api/v1/search/place-pulls. Staff, behind the search_places and places_bulk flags (both
must be on). Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Same fields as estimate-place-pull:
query, countries or worldwide=true, and the optional min_rating, min_reviews, has_website and
max_places.

Answers 201 with the pull (status queued) and reads in the background, about 10 pages a minute
across every running pull. Poll get-place-pull until status is not queued or running; read the
places with list-place-pull-places, also while it runs.

Cost: each page is 1 credit (1,000 millicredits), like a places search page, so the pull spends
up to the estimate's credits. Pages it reads from Google count against the workspace's monthly
bulk budget (Google Maps data requests; pages from Kenso's store spend none). A pull that meets
a budget or runs out of credits stops with status stopped, keeps what it found and says why in
stopReason.

Errors: 409 invalid_state (the workspace already has a pull queued or running: cancel it or
wait), 402 plan_limit_reached (not enough credits for the estimate; nothing starts), 429
quota_exceeded (no bulk budget left this month; Retry-After runs to the 1st), 400
validation_failed, 404 (flags off).

estimate-place-pull

Read. Early access: needs places_bulk, search_places on for the workspace. POST https://api.ken.so/v1/search/place-pulls/estimates

Body (json): countries array, hasWebsite boolean, maxPlaces integer, minRating number, minReviews integer, query string, worldwide boolean

Estimate a bulk Google Maps place pull: what it would cover and cost. Free, starts nothing. Show the user credits and coverage and get their yes before create-place-pull.

POST /api/v1/search/place-pulls/estimates. Staff, behind the search_places and places_bulk flags
(both must be on). Sends Ken-Version 1.1 and X-Ken-Workspace-Id.

A pull reads every Google Maps place matching query across whole countries or the world, the
region's biggest cities first, in the background. query is what to look for ("dentists").
Give countries (two-letter codes like ["de", "fr"], at most 50) or worldwide=true, not both.
Optional filters: min_rating (0-5), min_reviews, has_website (default true keeps only places
with a website; false keeps all) and max_places (the most places the pull keeps, default 1,000,
at most 25,000).

Returns data: region, plannedCities and plannedPages (the plan for max_places), then how far
this month's bulk budget lets it run: cities, pages, expectedPlaces and credits. The budget:
requestsNeeded (pages Kenso's store does not hold, one Google Maps data request each),
requestsAllowed, workspaceRequestsLeft, workspaceRequestLimit and budgetResetAt (the 1st of
next UTC month). coverage says it in words ("Covers Germany's 38 biggest cities, about 31% of
its population."). canStart is false with blockedReason active_pull (one pull at a time),
budget_exhausted or insufficient_credits.

Cost: free. A started pull spends up to credits (1 credit a page, like a places search page)
and counts against the workspace's monthly bulk budget: every workspace shares one Google Maps
data plan, so pulls get a monthly share per workspace and one for all pulls together, and never
the reserve normal searches live on.

get-place-pull

Read. Early access: needs places_bulk, search_places on for the workspace. GET https://api.ken.so/v1/search/place-pulls/{pullId}

Path: pullId

Read one bulk place pull: status, progress and spend. Free. Poll it until status is not queued or running.

GET /api/v1/search/place-pulls/{pull_id}. Staff, behind the search_places and places_bulk flags.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. pull_id is the id create-place-pull or
list-place-pulls returned; another workspace's pull is not_found.

Returns data: id, status, stopReason, error, query, countries (empty when worldwide), worldwide,
region, maxPlaces, minRating, minReviews, hasWebsite, citiesTotal, citiesDone, placeCount,
pageCount, requestsUsed (Google Maps data requests; pages from Kenso's store spend none),
credits, millicredits, coverage ("Germany's 40 biggest cities"; null before the first page),
createdAt, startedAt and finishedAt.

status: queued and running are still going; succeeded (stopReason completed or place_cap),
stopped (a limit ended it early: workspace_budget, bulk_budget, monthly_reserve, monthly_limit,
insufficient_credits or feature_off), canceled, and failed (vendor_unavailable or
search_refused). Every end keeps the places found. Poll about once a minute: the pull reads
about 10 pages a minute across every running pull.

list-place-pull-places

Read. Early access: needs places_bulk, search_places on for the workspace. GET https://api.ken.so/v1/search/place-pulls/{pullId}/places

Path: pullId

Query: cursor string, limit integer

List the places a bulk pull found, in the order it found them. Free. Readable while the pull runs. Same place shape as search(operation="search-places").

GET /api/v1/search/place-pulls/{pull_id}/places. Staff, behind the search_places and
places_bulk flags. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. limit is 1-200, default 200;
cursor is pagination.nextCursor from the previous page.

Returns data (places, each once: id plc_..., name, location, address, phone, website, domain,
rating, categories, hours, alreadyProcessed, accountId and more) and pagination {hasMore,
nextCursor}. Cost: free, the pull already paid for its pages. Open a place with
search(operation="get-place").

list-place-pulls

Read. Early access: needs places_bulk, search_places on for the workspace. GET https://api.ken.so/v1/search/place-pulls

Query: cursor string, limit integer

List the workspace's bulk place pulls, newest first. Free. Each pull has its status, progress and spend, as get-place-pull returns it.

GET /api/v1/search/place-pulls. Staff, behind the search_places and places_bulk flags. Sends
Ken-Version 1.1 and X-Ken-Workspace-Id. limit is 1-50, default 20; cursor is
pagination.nextCursor from the previous page.

Returns data (pulls, each like get-place-pull) and pagination {hasMore, nextCursor}.