Merge Unified's Yelp integration Merge Agent Handler's Yelp MCP server

Connect your AI Agents to Yelp in minutes

Merge lets you securely connect your agents to Yelp and thousands of tools instantly

Start building for free

Read docs

Yelp

Learn more about Merge Agent Handler

Available tools

autocomplete

Get autocomplete suggestions for search text. Returns matching terms, businesses, and categories. Optionally provide lat/lng for location-aware results.

search_businesses

Search businesses by term, location, category, price, and more. Requires location or latitude/longitude. Returns up to 50 per page, 1000 total via offset pagination.

search_businesses_by_phone

Find businesses by phone number. Phone must include + and country code (e.g. '+14157492060').

match_business

Match a business by name, address, city, state, and country. Returns best-matching Yelp business. Use match_threshold='none' to get all potential matches.

get_business

Get detailed info for a business by ID or alias, including hours, photos, price, rating, and location. Use search_businesses to find IDs.

search_food_delivery

Search businesses that offer food delivery. Requires location or latitude/longitude. Currently US-only.

get_service_offerings

Get service offerings for a business (e.g. plumbing, electrical). Requires Yelp Partner API access.

get_engagement_metrics

Get engagement metrics (page views, ad clicks, calls, etc.) for one or more businesses. Requires Yelp Partner API access.

get_business_insights

Get business insights including review trends and competitive benchmarks. Requires Yelp Partner API access.

get_food_and_drinks_insights

Get food and drink insights for a business, including trending items. Requires Yelp Partner API access.

get_risk_signal_insights

Get risk signal insights for a business (e.g. health inspection issues). Requires Yelp Partner API access.

list_categories

List all Yelp business categories. Optionally filter/translate by locale. Returns alias, title, and parent categories.

get_category

Get details for a specific category by alias (e.g. 'pizza'). Use list_categories to find valid aliases. Requires developer beta.

search_events

Search for events by location, category, date range, and more. Requires location or lat/lng. Supports offset pagination. Requires developer beta.

get_event

Get details for a specific event by ID. Use search_events to find event IDs. Requires developer beta.

get_featured_event

Get the featured event for a location. Requires location or latitude/longitude. Requires developer beta.

get_reviews

Get reviews for a business. Supports pagination via limit/offset and sorting by 'yelpsort' or 'newest'. Use searchbusinesses to find business IDs.

get_review_highlights

Get review highlight excerpts for a business, showing key themes from reviews. Use search_businesses to find business IDs.

validate_credential

Validate Yelp API credentials by making a test API call.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Yelp MCP server

What is a Yelp MCP server?

It’s an MCP server that lets you access data and functionality from Yelp via tools. Your agents can use these tools to search for businesses, gather specific business insights (e.g., trending food items), list business categories, and more.

Yelp offers an official MCP server here. You can also access MCP servers for Yelp via 3rd-party integration providers, like Merge.

How can I use Yelp’s MCP server?

Local lead discovery and prospect list building: Find high-intent businesses by category and geography (e.g., “plumbers in Austin” or “IT services near SoHo”), then push results into a CRM or outbound tool

Location intelligence for sales territory planning: Estimate density and distribution of target business types across neighborhoods to prioritize where to sell, open a new location, or run a local campaign

Competitive benchmarking for multi-location operators: Track competitor ratings, review volume, price tiers, and category positioning across markets to inform pricing, positioning, and expansion strategy

Vendor and partner sourcing (procurement): Identify and shortlist vendors (caterers, cleaning services, agencies, contractors, etc.) with filters like rating thresholds, volume of reviews, and distance

Customer support and issue triage for a brand’s locations: Monitor reviews for specific locations, detect spikes in negative sentiment, and route issues to the right regional operator or support queue (you can even pair with auto-generated response drafts)

What are some popular tools for Yelp’s MCP server?

Here are commonly-used tools across data types:

Businesses:

<code class="blog_inline-code">search_businesses_by_phone</code>
<code class="blog_inline-code">get_business</code>
<code class="blog_inline-code">match_business</code>
<code class="blog_inline-code">get_business_insights</code>

Categories:

<code class="blog_inline-code">search_businesses</code>
<code class="blog_inline-code">list_categories</code>
<code class="blog_inline-code">get_category</code>

Reviews

<code class="blog_inline-code">get_review_highlights</code>
<code class="blog_inline-code">get_reviews</code>

What makes Merge Agent Handler’s Yelp MCP server better than alternative Yelp MCP servers?

Merge Agent Handler provides infrastructure that manages the full lifecycle of AI agent tool usage across connectors.

Secure authentication and credential management: Merge handles connector authentication flows and credential storage so agents can safely access external systems without developers building custom auth infrastructure

Enterprise-grade security with data loss protection (DLP): The platform scans tool inputs and outputs for sensitive information and can block or redact data based on configured rules. This prevents misuse of sensitive data when agents interact with external tools

Real-time observability and activity logging: Every tool call and underlying API request can be tracked through detailed logs. These logs are fully searchable, allowing teams to audit behavior, debug agents, and monitor tool usage

Evaluation and testing framework: The Evaluation Suite allows teams to validate tool outputs against expected results before deploying agent workflows to production

Can I set custom security rules for Yelp tool calls in Merge Agent Handler?

Yes, Merge Agent Handler includes a security gateway with DLP that scans tool inputs and responses for sensitive information and applies security policies configured in the platform.

These rules can block, redact, or mask sensitive data fields before the agent receives or transmits the data.

Here are some examples:

Block returning personal data from reviews: If a Yelp review contains an email, phone number, or address, mask or redact it in the tool output before the agent sees it

Hard-limit bulk pulls: Block (or cap) any Yelp search that tries to fetch an unusually large number of businesses or reviews in one run to reduce data hoovering and misuse

Allowlist geographies: Only allow searches within approved cities, states, or radius limits (e.g., “within 10 miles of NYC”), and block everything else to prevent broad scraping behavior

Category allowlist / denylist: Only allow specific Yelp categories relevant to the workflow (for example, “restaurants” for a food-delivery agent), and block sensitive or irrelevant categories

Keyword denylist in queries: Block searches containing sensitive keywords (for example, “escort”, “weapons”, “fake IDs”) or other policy-prohibited intents

How can I start using Merge Agent Handler’s Yelp MCP server?

You can take the following steps:

1. Create an Agent Handler account. Then grab your Agent Handler API key from the dashboard. This API key is what your MCP client uses to authenticate to the Agent Handler MCP endpoint.

2. Create a Tool Pack for your Yelp workflow (e.g., “Local business search”). Tool Packs define which connectors and tools the agent is allowed to call.

3. Add the Yelp connector to that Tool Pack. Only select the specific Yelp tools you want exposed (e.g., business search).

4. Create a Registered User (or use an existing one). This is for the end user or service account your agent will act on behalf of. Registered Users are the identity boundary that scopes credentials and audit logs.

5. Authenticate Yelp for that Registered User (or set up shared auth, if you want one org-level Yelp credential reused across users). In practice, this is typically done via Merge Link in your product so end users can connect without you handling credentials directly.

6. Connect your MCP client to the Agent Handler MCP endpoint. Use the Tool Pack and Registered User, and include your Agent Handler API key as a bearer token in the Authorization header. Your client will then be able to list_tools and call_tool for the Yelp tools in that Tool Pack.

7. Test and monitor by running a few real prompts. Then use the fully-searchable logs (and optionally rules/alerts) to verify the tool calls and outputs look right before rolling it out broadly.