Connect your AI Agents to Foursquare in minutes
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 get_self_lists 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.
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}
11Open 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}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 }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}FAQs on using Merge's Foursquare MCP server
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.
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
