Get contextual intelligence about Merchant API from the coding assistant of your
choice. Within your integrated development environment (IDE), you can now access
the developer documentation integration using the Model Context Protocol (MCP)
service. This service accelerates your development for integration and migration
workflows by providing your coding assistant with authoritative context from
official Google API documentation.

For more information on the protocol itself, see the [Model Context Protocol
standard](https://modelcontextprotocol.io/).

## Overview

When migrating from Content API for Shopping to Merchant API or building a new
integration, you need to understand new service structures, resource names, and
methods. The MCP service simplifies this by providing official documentation and
code samples to your coding assistant.

The service utilizes a highly specialized Retrieval-Augmented Generation (RAG)
backend. When you ask your MCP-enabled IDE coding assistant a question about
Merchant API, the service retrieves the most relevant snippets of text and code
from [Google's official resources](https://developers.google.com/merchant/api/guides/devdocs-mcp#knowledge-base-sources) and returns them as
context to your coding assistant. This lets your assistant provide accurate,
up-to-date answers without you ever having to leave your development
environment.

> [!NOTE]
> **Note:** The [Merchant API Terms and
> Conditions](https://developers.google.com/merchant/api/guides/terms) govern this service, and it prioritizes developer privacy. The service provides authoritative, publicly available documentation context to your coding assistant. The assistant you use determines the queries sent to the service. As a best practice, avoid sending sensitive or proprietary information.

## How it works

Developer documentation integration using MCP integrates into a modern,
AI-assisted development workflow:

1. You ask a question in your MCP-compatible coding assistant or Agent. This can be a natural language question, request for a Merchant API code sample or even a request to directly translate your code to Merchant API.
2. Your coding assistant sends a request for context to the MCP endpoint.
3. The MCP service searches its indexed collection of official Merchant API documentation, guides, and code samples to find the most relevant information.
4. The service returns these authoritative snippets as context to your coding assistant.
5. Your coding assistant uses this high-quality context to generate a precise and helpful answer to your original question or to perform a code translation task.

## Getting started

To use MCP, follow these steps:

### 1. Use a compatible tool

Open an IDE or coding assistant that supports the Model Context Protocol with
streamable HTTP transport.

### 2. Endpoint configuration

To connect your IDE or coding assistant to MCP, use the provided remote endpoint
details which may require you to input either the direct service URL or the MCP
definition (depending on your tool's configuration).

The service URL is:

    MCP Server Name: "MAPI Docs MCP"
    MCP Server URL:  "https://merchantapi.googleapis.com/devdocs/mcp/"
    MCP Server Protocol: "http"

Configuration setups:

### Antigravity

Follow instructions in the [Antigravity documentation](https://antigravity.google/docs/mcp).

    {
        "mcpServers": {
            "mapi-devdocs": {
                "command": "npx",
                "args": [
                    "-y",
                    "mcp-remote",
                    "https://merchantapi.googleapis.com/devdocs/mcp"
                ]
            }
        }
    }

### Visual Studio Code

Follow instructions in the [Visual Studio Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

    {
        "servers": {
            "mapi-devdocs": {
                "type": "http",
                "url": "https://merchantapi.googleapis.com/devdocs/mcp/"
            }
        }
    }

> [!NOTE]
> **Note:** This endpoint is publicly accessible and does not require authentication. Rate limits are in place to ensure fair usage and service stability.

### 3. Add agent instructions (optional)

To enable your agent to directly translate code using MCP, provide it with the
[System Instructions: MerchantIntegrator Agent
Protocol](https://github.com/google/merchant-api-samples/blob/main/devdocs_mcp_instructions.md).
These instructions guide the agent on how to correctly utilize MCP for code
translation. Depending on your tool, you can provide these instructions either
in the system instructions configuration or as an additional context file for
the agent.

## Example usage scenarios

MCP can accelerate your workflow in these common use cases.

### Scenario 1: Migrate `products.insert` code

You can ask the agent to directly migrate a Content API for Shopping
`products.insert` integration code to Merchant API.

**User prompt:**
> "Migrate `products.insert` code to Merchant API"

By providing your agent with [System Instructions: MerchantIntegrator Agent
Protocol](https://github.com/google/merchant-api-samples/blob/main/devdocs_mcp_instructions.md)
and access to MCP, your agent can translate Content API for Shopping code to
Merchant API code directly in your IDE. In this case, it will identify
`productInputs.insert` as the equivalent call and map the product attributes
from the old format to the new format required by Merchant API. It can also
update required imports and dependency management file (for example
`requirements.txt`, `pom.xml` or `package.json`). You can instruct the agent to
do the changes in place or to create a new folder.

### Scenario 2: Find equivalent functionality

You have an existing application using the Content API for Shopping and need to
update it. You can ask about a specific legacy method to get details on the new
implementation and a relevant code sample.

**User prompt:**
> "What is the Merchant API equivalent for the accountstatuses.get method in the
> Content API for Shopping?"

The MCP service provides context from the official migration guides and
reference documentation, letting your assistant respond with a detailed answer,
including the new API name, `accounts.issues`.

### Scenario 3: Finding a code sample

You are implementing a new feature and need a practical example to follow.

**User prompt:**
> "Show me a Python code sample for adding a new shipping service using Merchant
> API."

The MCP service retrieves relevant code samples from the official Google GitHub
repositories and developer guides. Your assistant can then present a complete,
ready-to-adapt code block.

### Scenario 4: Understanding API concepts

You encounter a new concept or want to understand the structure of a resource or
the overall Merchant API pattern.

**User prompt:**
> "How do I update the inventory for a product using Merchant API?"

The MCP service returns context from the products resource documentation and
relevant guides. Your assistant can then explain how to use the
`accounts.productInputs.insert` method and provide the partial product resource
containing just the `productId` and the inventory-related fields you need to
update.
> "How do I authorize my application calls with Merchant API?"

The MCP service retrieves context from the official authentication guides, which
cover different authorization methods. Your assistant can then explain the
primary options available, such as using a service account for server-to-server
interactions or an OAuth 2.0 client ID when acting on behalf of a user.

### Scenario 5: Adapting to API changes

Merchant API introduces new patterns --- such as batching requests --- that differ
from the Content API for Shopping. The Content API for Shopping uses specific
`custombatch` methods, while the Merchant API uses a built-in, generic HTTP
batching feature.

**User prompt:**
> "What is the new way to do a products.custombatch in Merchant API?"

The MCP service retrieves context from [Refactor code for concurrent
requests](https://developers.google.com/merchant/api/guides/compatibility/refactor-concurrent-requests)
explaining that dedicated `custombatch` methods don't exist in Merchant API.
Instead, it provides documentation on using HTTP batching with a `Content-Type`
of `multipart`. Your assistant can then explain how to construct a single HTTP
request containing multiple API calls, sent to the
`https://merchantapi.googleapis.com/batch/{sub-api}/v1` endpoint, and provide an
example of how to structure the multipart request. This turns a potentially
confusing migration task into a guided process.

### Scenario 6: Translate a reporting query

You can ask the agent to translate a reporting query from Content API for
Shopping to Merchant API.

**User prompt:**
> "Migrate this reporting query from Content API to Merchant API: SELECT
> metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView
> WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

The MCP service retrieves the latest reporting reference documentation,
developer guides, and migration guides. Based on this information, it transforms
the query to the new structure and updates the fields to their new names and
values.

## Knowledge base sources

The MCP service builds its knowledge base exclusively from public and official
sources to ensure the context it provides is accurate and reliable. The service
indexes the entire content of the official developer site and code sample
repository, including:

- **[Merchant API Developer
  Site](https://developers.google.com/merchant/api/):** All guides, reference material, and documentation.
- **[Merchant API Apps Script
  service](https://developers.google.com/apps-script/advanced/merchant-api)**: Example of Merchant API usage from Apps Script.
- **[Official Code Samples](https://github.com/google/merchant-api-samples):** All official, Google-provided code samples for Merchant API from the GitHub repository.
- **[Client
  libraries](https://developers.google.com/merchant/api/client-libraries):** All official client libraries supported by the Merchant