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

Connect your AI Agents to Foursquare in minutes

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

Start building for free

Read docs

Foursquare

Learn more about Merge Agent Handler

Available tools

create_checkin

Check in at a venue. Use search_venues to find venue IDs. Optionally add a shout message.

get_checkin

Get checkin details including venue, shout, likes, and comments.

delete_checkin

Delete a checkin. Only the creator can delete their own checkins.

create_list

Create a new Foursquare list. Optionally set description and collaborative mode.

get_list

Get list details including items (venues). Use getselflists to find list IDs.

update_list

Update a list's name, description, or collaborative setting.

delete_list

Delete a list. Only the creator can delete their own lists.

add_list_item

Add a venue to a list. Use search_venues for venue IDs. Optionally add text.

delete_list_item

Remove an item from a list. Use get_list to find item IDs.

autocomplete

Autocomplete for venues and places. Provide query with optional ll or near for location bias.

get_recommendations

Get venue recommendations near a location, optionally filtered by query. Provide ll or near.

add_tip

Add a tip to a venue (max 200 chars). Use search_venues to find venue IDs.

get_tip

Get tip details including text, venue, author, and likes.

delete_tip

Delete a tip. Only the author can delete their own tips.

get_self

Get the authenticated user's profile including name, home city, checkin/list/tip counts.

get_self_checkins

Get the authenticated user's checkin history with pagination. Filter by before/after timestamps.

get_self_lists

Get the authenticated user's lists. Filter by group: created, edited, followed, friends, suggested.

get_self_tips

Get tips the authenticated user has written. Sort by recent, nearby, or popular.

get_self_tastes

Get the authenticated user's taste preferences (e.g., 'craft beer', 'sushi', 'live music').

validate_credential

Validate Foursquare credentials by fetching the current user profile. Returns {success, message}.

search_venues

Search venues by location+query. Provide ll or near. Use get_categories for category IDs. Returns paginated results.

get_venue

Get venue details by ID including location, categories, ratings, hours, and stats. Use search_venues to find IDs.

get_venue_photos

Get photos for a venue. Build URLs: prefix + {width}x{height} + suffix. Use offset for pagination.

get_venue_tips

Get tips for a venue. Sort by friends, recent, or popular. Use offset for pagination.

get_venue_hours

Get operating hours for a venue with timeframes and open/close times.

get_venue_attributes

Get venue attributes like outdoor seating, Wi-Fi, live music, parking, and more.

get_categories

Get all venue categories as a hierarchical tree with IDs and names. Use category IDs to filter search_venues.

get_trending_venues

Get trending venues near a lat/lng coordinate. Returns venues with high recent activity.

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 Foursquare MCP server

What is a Foursquare MCP?

A Foursquare MCP gives your agents access to Foursquare's venue and location data via tools. Your agents can invoke these tools to search for places, retrieve venue details, generate location recommendations, track check-ins, and more.

Foursquare offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Foursquare MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Location-aware recommendation engine: An agent takes a user's current city and preferences, queries Foursquare for venue recommendations in matching categories, and returns a ranked list of places with hours and ratings

Venue data enrichment: When a new business record is created in a CRM, an agent searches Foursquare for the matching venue, retrieves its attributes and hours, and writes the enriched data back to the record automatically

Field team check-in logging: A sales or field operations agent logs a check-in at a venue after a rep completes a site visit, creating a timestamped record that syncs with activity tracking in another system

Trending venue monitoring: An agent pulls trending venues in a target market on a recurring schedule and surfaces the results to a marketing or research team as part of a competitive intelligence workflow

What are popular tools for Foursquare's MCP server?

Here are some of the most commonly used tools:

search_venues: queries Foursquare for venues matching a search term, category, and location. Use this when an agent needs to find a specific type of place in a given area as part of a discovery or enrichment workflow

get_venue: retrieves full details for a specific venue, including name, address, category, and metadata. Helpful when an agent has a venue ID and needs to pull structured information before taking a downstream action

get_recommendations: returns personalized venue recommendations based on location and context. Good for agents building itinerary or discovery features that need ranked, relevant results rather than raw search output

get_venue_hours: fetches the operating hours for a specific venue. Call this when an agent needs to confirm whether a location is open before routing a user, scheduling a visit, or triggering a delivery

get_trending_venues: returns venues currently trending in a given area based on recent check-in activity. Useful for agents that surface market intelligence or foot traffic signals on a recurring basis

create_checkin: logs a check-in at a venue on behalf of the authenticated user. Call this when an agent needs to record a physical visit as part of a field activity or loyalty tracking workflow

What makes Merge Agent Handler's Foursquare MCP server better than alternative Foursquare MCP servers?

Here is what sets Merge Agent Handler's Foursquare MCP server apart from building or using an alternative:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Foursquare, this means you can prevent user location history, check-in data, and personal account details from being exposed even when the agent has broad read access

Managed authentication and credentials: Merge stores and refreshes Foursquare credentials on your behalf. You never expose raw API keys or OAuth tokens to an agent or handle token rotation manually

Real-time observability and audit trail: Every tool call made against Foursquare is logged with timestamp, tool name, input parameters, and response metadata. You can audit exactly what an agent queried or wrote without instrumenting anything yourself

Tool Packs and controlled access: Tool Packs let you bundle specific Foursquare tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Foursquare MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Foursquare connector. Choose which tools to include: enable read tools for venue discovery and enrichment use cases, or add write tools if your agent needs to create check-ins or manage lists.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Foursquare by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Foursquare tools are now accessible through that endpoint.