The 2GIS MCP server is a ready-made adapter that lets an AI agent call existing 2GIS APIs: search for companies and addresses, convert an address into coordinates, build routes, calculate travel time, and draw a map with markers. You can connect it in two ways: to the 2GIS cloud server at the address in the documentation, or to your own server built from open-source code. You need a 2GIS API key: the free demo key works for 30 days with request limits, after which you need a paid subscription on the same pricing terms as direct API calls. For business, the main benefit is that the agent stops making up addresses and distances and pulls them from geodata.
Prepared by AIrassvet based on 2GIS documentation and verified publications October 12, 2026. It is intended for leaders in logistics, delivery, field service, and sales, as well as developers who connect AI agents to business processes. This is a practical guide: it includes server option selection, setup steps, verification, pricing calculations, and a launch checklist. We did not test the 2GIS MCP server on our own workloads; all parameters are taken from the developer documentation. AIrassvet is not affiliated with 2GIS; the section at the end of the article describes the publisher's services.
Contents
- Quick take: what you need to know
- What the 2GIS MCP server is
- Which tools are available to the agent
- Cloud or local server: how to choose
- How to connect: step-by-step guide
- How much it costs and how requests are billed
- Business use cases: where an agent needs geodata
- How to frame tasks for the agent
- Limitations and risks
- Launch checklist
- FAQ
- Original sources and verification method
Quick take: what you need to know
- The MCP server does not provide new geodata: it gives the agent access to the same Places, Geocoder, Routing, and other 2GIS APIs through a standard protocol.
- There are two options: the 2GIS cloud server (no installation, requires a client with Streamable HTTP) and a local distribution from open source code (you deploy it yourself).
- You need an API key: the 30-day demo key includes all required APIs, but with request limits; for ongoing use, you need a subscription.
- Pricing is the same as for the API: you pay for successful requests and billing units — routes, point combinations in a distance matrix, courier task volume.
- The agent needs the right sequence: first coordinates from the address, then the route — otherwise it may build a route using invented coordinates.
- For bulk processing, MCP is not needed: batch geocoding of thousands of addresses is cheaper and more reliable through direct API calls without a language model.
What the 2GIS MCP server is
MCP (Model Context Protocol) is an open protocol that gives an AI agent access to external tools and data in a unified format. The MCP server defines which tools are available, accepts agent calls, and returns results.
According to 2GIS documentation, the API platform's MCP server gives agents access to maps, addresses, routes, and business listings data. The workflow looks like this:
- The user gives the agent a task, for example, to find all 24/7 pharmacies near a location.
- The agent decides which geodata is needed and calls the MCP server tool.
- The server queries the appropriate 2GIS API — for example, the Places API to search for objects.
- The agent receives the result and forms the response.
On September 24, 2026, the server launch was reported by Kod.ru citing 2GIS press service. The outlet emphasizes that this is not new geodata and not a separate API for neural networks, but a ready-made interface to existing services. The local server code was published in the 2GIS GitHub repository.
Why this matters for business. A language model without access to geodata can confidently write plausible but fabricated addresses, distances, and travel times. The MCP server replaces the model's guesses with geoservice answers, and the agent takes over what previously required a separate integration: understanding a natural-language request, choosing the right service, and tying the result to the task.
Which tools are available to the agent
The tool set for the cloud and local server differs, and this is important to consider when choosing.
Cloud server (documentation):
| Tool | What it does | 2GIS API |
|---|---|---|
| search_places | search for places, organizations, and addresses | Places API |
| geocode_address | address → coordinates | Geocoder API |
| build_route | route for different modes of transport, time, and distance | Routing API |
| calculate_distance_matrix | time and distance between pairs of points | Distance Matrix API |
| render_static_map | static map with markers in PNG | Static API |
| auth_probe | check the key and API availability | all of the above |
The utility tools server_info, list_resources, and read_resource work without a key: they show the server status and API parameter reference.
Local server (documentation):
| Tool | What it does | 2GIS API |
|---|---|---|
| search_poi | search for places and businesses by query and coordinates | Places API, Geocoder API |
| calculate_route | route, time, and distance | Routing API |
| geocode | address → coordinates | Geocoder API |
| reverse_geocode | coordinates → address | Geocoder API |
| create_map_view | static map with markers in PNG | Static API |
| calculate_isochrone | area reachable from a point within a specified time | Isochrone API |
What does this mean: the distance matrix is available in the cloud version, while reverse geocoding and isochrones — reachable areas within a given time — are available in the local version.
Cloud or local server: how to choose
| Criterion | Cloud server | Local server |
|---|---|---|
| Setup | not required, server address from the documentation | clone the repository, npm install, npm run build |
| Client requirements | Streamable HTTP and static headers; clients that only support Plain SSE or stdio are not supported | any MCP client; over HTTP — through Supergateway |
| Network | outbound HTTPS connections to the 2GIS server | requests go only to the 2GIS API |
| Tools | distance matrix and key validation are available | reverse geocoding and isochrones are available |
| Control | server and its updates are managed by 2GIS | server, access, and logging — under your control |
| Fully local model | depends on the client | the documentation describes working with LM Studio: the model runs on your computer, and the server connects only to the 2GIS API |
Selection rule: for a pilot project and to test the idea, choose the cloud server. The local option is needed when the agent runs inside your infrastructure with a local model, when you need isochrones or reverse geocoding, or when security requires the intermediary server to be under your control.
In both cases, the actual geodata requests go to the 2GIS API. If user questions contain personal or business data, make sure the agent sends only addresses and coordinates to the geoservice, not the entire order context. For more on data-sharing rules for external AI services, see the article on whether client data can be sent to AI.
How to connect: step-by-step instructions
Step 1. Get an API key
Register in the 2GIS Manager Platform account and get a demo key (30 days, request limits, all required APIs connected automatically) or purchase a subscription. For the local 2GIS server, two keys are recommended: one for maps and search (Static, Geocoder, Places API), and a second for navigation (Routing, Isochrone API). According to the documentation, the number of keys does not affect the subscription price, and separate keys help control usage. two keys: one for maps and search (Static, Geocoder, Places API), the second for navigation (Routing, Isochrone API). According to the documentation, the number of keys does not affect the subscription price, and separate keys help control usage.
Step 2a. Cloud server: add the address in the client
Cloud server address: https://mcp-2gis.api.2gis.com/mcp. The key is passed in the header. In the examples below, replace the values in angle brackets and the variable $DGIS_API_KEY with your own key and paths. For Claude Code, the documentation gives this command:
claude mcp add --transport http 2gis https://mcp-2gis.api.2gis.com/mcp \
--header "Authorization: Bearer $DGIS_API_KEY"For AI assistant-building platforms, including GigaChat, the documentation offers a universal configuration with the X-2GIS-API-Key header — it is needed if the Authorization header is already in use on the platform:
{
"mcpServers": {
"2gis": {
"type": "streamable_http",
"url": "https://mcp-2gis.api.2gis.com/mcp",
"headers": { "X-2GIS-API-Key": "<API_KEY>" }
}
}
}Step 2b. Local server: build and connect
Clone the repository, run npm install and npm run build — the file dist/index.jswill appear. In the client configuration, specify launch via Node.js and two keys in environment variables:
{
"mcpServers": {
"2gis": {
"command": "node",
"args": ["<PATH_TO_REPOSITORY>/dist/index.js"],
"env": {
"MAPGL_API_KEY": "<MAP_AND_SEARCH_KEY>",
"ROUTING_API_KEY": "<NAVIGATION_KEY>"
}
}
}
}If you use a single key, specify it in both variables. If the server is deployed on a remote machine with HTTP access, the documentation recommends connecting to it through Supergateway.
Step 3. Check that it works
Ask the agent to verify the key and available tools. For a cloud server, the documentation expects the following call chain tools/list → server_info → auth_probe. Then give a specific task — for example, find three coffee shops near a selected point and plot a walking route to the nearest one. The agent should call location search first, then route building.
Typical cloud server errors: MCP_API_KEY_REQUIRED — the key was not provided; MCP_API_KEY_INVALID — the key is invalid or the required APIs are not enabled for it; MCP_2GIS_API_UNAVAILABLE — the service is temporarily unavailable.
How much it costs and how requests are counted
Under 2GIS pricing rules, the MCP server does not change the prices: the rates and limits of the standard API subscription apply. Access is purchased in units of billing credits, and a request with HTTP status code 200 or 204 is considered successful.
| Service | What counts as one unit | Documentation example |
|---|---|---|
| Places, Geocoder, Static API | successful request | — |
| Routing API | route built for each origin-destination pair | 5 pairs in one request = 5 calculations |
| Distance Matrix API | each origin and destination point combination | 2 × 3 points = 6 calculations |
| TSP API (courier task) | number of points × number of couriers | 5 points × 2 couriers = 10 calculations |
Why this matters for the agent. The language model does not see pricing and may request extra data “to be safe.” For example, if a dispatch agent compares 10 vehicles with 20 orders through the distance matrix, that is 10 × 20 = 200 units for a single question (our calculation based on the rule in the documentation). Repeat it for every dispatcher follow-up, and the package will run out faster than you planned.
Demo key limits as of the review date: 1,000 requests each to Places, Geocoder, Routing, and Distance Matrix API, and 30,000 requests to Static API over the full term. Subscription plans have per-minute limits, for example 600 units per minute for Places, Geocoder, and Routing API, and 3,000 for Static API. See the current packages and pricing in your account dashboard: we are not listing them here because they depend on the subscription.
Business use cases: where geodata helps the agent
Order address verification. An agent that takes orders from a messenger app or email converts the address into coordinates, clarifies ambiguous options with the customer (“Lenin Street exists in two districts”), and saves an already verified point in the CRM. This can reduce the number of failed courier trips, but the impact should be measured on your own data.
Dispatching field service calls. The agent selects the nearest available technician and gives the travel time, while the dispatcher confirms the assignment. For more on field service tasks, see the article on AI for service teams and field technicians.
Logistics and delivery. The agent answers questions like “will we make it by 6:00 PM,” “which warehouse is closer to the customer,” and prepares a route map with stop points for the driver. For carriers, it is useful to connect this with document workflows — see AI for transportation companies.
Service areas and analytics. With isochrones (in the local version), the agent shows which addresses fall within a 30-minute delivery zone from the warehouse or which districts can be reached from the new office within a specified time.
Partner and point-of-sale search. The agent finds organizations in a specified category in a given area — for example, pharmacies or auto repair shops — for the sales team or for checking the competitive landscape before opening a location.
Where you do not need an agent. If the task is to batch geocode a database of tens of thousands of addresses or recalculate routes overnight, the language model only adds cost and the risk of errors. Those tasks are handled with direct API calls and regular code, while the agent is used where the request comes in natural language.
How to phrase tasks for the agent
2GIS documentation gives five recommendations that should be included in the agent’s system prompt:
- Specify the sequence: “first get coordinates from the address, then build the route.” This helps prevent a common mistake — creating a route using made-up coordinates.
- Break large tasks into parts: instead of one 25 × 25 point matrix, use several smaller ones.
- Specify the transport type and restrictions: “by car without toll roads,” “on foot.”
- Specify the required number of results: “three nearest,” “five with the best rating.”
- Specify the response language explicitly.
You should also add business-side rules: what data the agent may send to the geoservice, how many calls are allowed per request, and when human approval is required — for example, before assigning a field visit or changing an order address. We covered how to define such rules in the article on technical specifications for an AI agent.
Limitations and risks
- The key is money. Documentation for some clients shows the key being passed directly in the server address. Such an address can easily end up in logs and screenshots; use header-based transmission where the client supports it, and a separate key with a limited quota for each agent.
- The agent may call tools unnecessarily. Set limits at the key level in your account dashboard and limit the number of calls per request in the agent settings.
- The agent’s response is not the geoservice’s response. The model may paraphrase the result incorrectly. For decisions that affect revenue, save the original call data and show it to a human.
- Toolkits differ. A scenario built on isochrones will not transfer to a cloud server unchanged, and a scenario built on a distance matrix will not transfer to a local server.
- The server code was published recently. The GitHub repository was created on August 24, 2026; before using it in production, check the license terms and update process.
- Dependence on an external service. If the API is unavailable, the agent should honestly report an error instead of substituting “approximate” data.
Launch checklist
- One scenario and one success metric have been chosen, such as the share of orders with a verified address.
- The server option has been selected: cloud or local, based on the tools required.
- The key has been issued; for production use, separate keys for search and navigation are configured, and limits are set.
- The key is passed in a header, not in the URL, and stored in secrets, not in code.
- The system prompt defines the sequence “address → coordinates → route” and the call limit.
- It has been determined what data the agent sends to the geoservice, and this has been approved by security.
- Actions that change an order or assignment require human confirmation.
- The server_info → auth_probe chain check has been completed, and there is a test with 20–30 real requests.
- The expected consumption of billing units per question and per month has been calculated.
- Logging for calls has been configured for troubleshooting.
Frequently asked questions
What is the 2GIS MCP server?
This is a server based on the open Model Context Protocol, through which an AI agent calls the 2GIS API: place and business search, geocoding, routing, static maps, and, depending on the version, a distance matrix or isochrones. It does not add new data — it is an interface to existing APIs.
How much does the 2GIS MCP server cost?
The server itself is not billed separately: 2GIS API subscription rates and limits apply, just as with direct requests. For testing, there is a free demo key for 30 days with a limit such as 1,000 requests to the Places API and 1,000 to the Routing API.
Can you deploy the 2GIS MCP server on your own infrastructure?
Yes. 2GIS publishes the local server code on GitHub: the repository is built with the npm install and npm run build commands. Even so, requests for geodata still go to the 2GIS API, while the server itself — and, if desired, the language model — remain local.
Which AI clients are supported?
The cloud server documentation describes integration with ChatGPT, Claude Desktop and Claude Code, Cursor, VS Code, Windsurf, Cline, Gemini CLI, assistant-building platforms including GigaChat, and a custom Python client. The local server documentation covers Claude Desktop, LM Studio, and Cursor.
How is the cloud server different from the local one?
The cloud version requires no installation and can calculate a distance matrix and validate a key. The local version is deployed on your own infrastructure and supports reverse geocoding and isochrones. The cloud version requires a client that supports Streamable HTTP.
Why does the agent route to the wrong place?
A common reason is that the agent builds a route from coordinates it made up itself without calling geocoding. 2GIS documentation recommends explicitly setting the sequence: first get coordinates from the address, then build the route.
Primary sources and verification method
We reviewed the documentation and publications on October 12, 2026. The toolkit, connection methods, prompt recommendations, errors, and billing rules were taken from 2GIS documentation; the release date and company comments came from the Code.ru publication; the repository creation date came from GitHub. The business scenarios, checklist, and sample unit calculation for a dispatching task are the AIrassvet editorial methodology, not the result of our testing.
- 2GIS: MCP server overview — how it works, options, prompt recommendations.
- 2GIS: cloud MCP server — address, tools, client configurations, validation, errors.
- 2GIS: local MCP server — tools, build, environment variables, keys.
- 2GIS: pricing and billing rules — billing units, per-minute limits, demo key limits.
- Code.ru, 09/24/2026: 2GIS released an MCP server for AI agents.
- GitHub: 2gis/2gis-mcp repository.
Limitations: we did not test the quality of agent responses with the MCP server on real tasks; we do not list package prices because they depend on the subscription; the documentation may change — verify the toolset and limits before launch.
How AIrassvet helps connect an AI agent to geodata
If you want the agent to verify addresses in orders, select the nearest contractor, or answer a dispatcher about travel time, the MCP server is only one piece: the agent also needs your orders, CRM, business rules, and action controls. On the AIrassvet website the areas directly related to this task are described:
- AI agents integrated with company communication channels and business systems, such as CRM, through which orders are received.
- Agentic automation of processes in accounting system interfaces, such as 1C.
- Deploying language models on company servers when order data cannot be sent to an external service.
- Process audit, testing on real requests, launch, and support.
The first step is to choose one scenario, for example verifying addresses in orders, describe the current baseline metric, where orders are stored, what data can be sent to the geoservice, and by what criterion you will consider the agent’s work successful.
Bottom line: geodata instead of model guesswork
The 2GIS MCP server addresses one of the most frustrating weaknesses of AI agents in logistics, delivery, and service — made-up addresses and distances. It does not add new data, but it lets the agent, on a natural-language request, call 2GIS geocoding, search, routing, and maps. The cloud server is a good fit for a quick pilot, while the local server works inside your own environment and for scenarios with isochrones.
Start with one scenario and a demo key: give the agent the sequence “address → coordinates → route,” limit the number of calls, calculate billing units per question, and test the agent on 20–30 real requests. If the answers match what a dispatcher would give, connect the CRM and move to a subscription.