How to Give an LLM Agent Access to Yandex Webmaster: Anatomy of an MCP Server over an External API

The author describes building an MCP server for Yandex Webmaster, which provides search analytics, indexing data, diagnostics, sitemaps, external links, and a recrawl submission feature. The key design choice is to group around two dozen endpoints into eight tools named by question rather than by endpoint: get_hosts, search_queries, get_indexing, get_diagnostics, list_sitemaps, get_external_links, recrawl_status, and recrawl_submit. This reduces model confusion from similar tool names. Several practical API pitfalls are covered: user_id must be fetched first; arrays are sent as repeated keys rather than CSV; 403 vs 401 are handled differently (403 means no rights to the host); different endpoints return different response shapes; error envelopes and auth header (OAuth instead of Bearer) differ from Yandex Metrica; throttling includes 429, 420, and quota error codes; recrawl is POST with JSON; empty responses should not be parsed. The interactive login uses authorization code with PKCE. Loopback redirect (http://127.0.0.1:53682/callback) is allowed by Yandex, contrary to the author's earlier belief, and eliminates code copy-paste. The port must be fixed to match redirect_uri, state is required for security, and fallback to manual code entry only on bind errors. Additionally, login is exposed as an MCP tool itself, so the agent can initiate login on its own without terminal access.