Contents
In brief
A Habr author has published a technical walkthrough of an MCP server that lets an LLM agent work with Yandex Webmaster data. Rather than exposing dozens of raw API endpoints, the server presents eight focused tools for tasks such as listing sites, inspecting search queries, checking indexing, and requesting a recrawl.
The article is as much about product design as it is about an API wrapper. The agent can discover that a user is not signed in, initiate Yandex ID authorization, and resume the task after the user grants access. The TypeScript implementation is available under the MIT license.
What happened
Yandex Webmaster holds data about a site's visibility before a visitor clicks: search impressions, clicks, indexing status, diagnostics, sitemaps, external links, and recrawl quotas. It complements Yandex Metrica, which covers what visitors do after they arrive on a page.
The server groups API calls by the question a person is trying to answer. For example, search_queries covers both top-query reporting and query trends, while get_indexing combines related views of crawling and indexed pages. This prevents an agent from having to choose among several nearly identical endpoint names.
One dedicated discovery tool, get_hosts, is essential because Webmaster host IDs cannot safely be guessed from a domain name. Having the model retrieve those IDs first avoids invalid requests and gives later tools a trustworthy starting point.
Why it matters
An MCP layer turns a conventional API into something an agent can use in a conversation. A request such as “show queries with many impressions but few clicks” becomes a well-defined tool call instead of a manual trip through several dashboard screens and a spreadsheet.
The article also argues that raw provider responses are the wrong interface for a model. The server filters diagnostics to active issues, sorts them by severity, and returns useful totals. Before a recrawl request, it reports the remaining daily quota so the agent can understand the cost of the action.
Error handling needs the same care. A 401 means the user must sign in again, while a 403 can mean that a valid token lacks access to the requested site. Conflating the two risks sending an agent into a pointless authorization loop.
In practice
When building an MCP server over an external API, start with the user's questions rather than a one-to-one mirror of its endpoints. The following choices from the implementation are broadly useful:
- Group calls by an outcome, using modes or parameters where they keep the tool understandable.
- Expose discovery for identifiers that a model cannot infer safely, and document that it must happen first.
- Rebuild verbose API responses into concise results with status, context, and a concrete next action.
- Keep read-only operations distinct from actions with side effects; show quotas before submitting a recrawl.
- Keep long-lived access tokens out of the MCP configuration and protect them in a dedicated local store.
The sign-in flow uses OAuth authorization code with PKCE and a local redirect address. A manual code path remains a fallback if the local server cannot bind its port, but real exchange errors should not silently turn into that fallback.
Takeaway
The central lesson is that authentication and errors are part of an AI tool's user experience, not setup work that must be completed in a terminal beforehand. A server that starts without a token and tells the agent what to do next makes installation much less fragile.
The design lessons apply beyond Yandex Webmaster: preserve meaningful API differences, cache successful results rather than failed promises, and phrase failures so an agent can make a correct next decision.