> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent

> Add AgentMall to your coding agent and search Walmart in test mode, with no account or key.

AgentMall's test mode is a hosted MCP server. It returns real Walmart search results and needs no account, key or card. Carts, checkout and orders need a test key.

## Server address

```text theme={null}
https://mcp.getagentmall.com/mcp
```

It uses the streamable HTTP transport, with no authentication.

## Add it to your client

> [tab] Claude Code
>
> Run this in your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http agentmall https://mcp.getagentmall.com/mcp
> ```
>
> Then start a new session. `/mcp` should list `agentmall` as connected.

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in your project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "agentmall": {
>       "url": "https://mcp.getagentmall.com/mcp"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Add this to `.vscode/mcp.json` in your project:
>
> ```json theme={null}
> {
>   "servers": {
>     "agentmall": {
>       "type": "http",
>       "url": "https://mcp.getagentmall.com/mcp"
>     }
>   }
> }
> ```
>
> Or open the Command Palette, run **MCP: Add Server**, choose **HTTP** and paste the address.

> [tab] Other clients
>
> Any MCP client that supports streamable HTTP can connect. Add a server named `agentmall` with the address above and no headers.

## Run a first search

Ask your agent:

```text theme={null}
Search Walmart for AA batteries with AgentMall and show me the top 3 with price and stock.
```

Your agent calls `search_catalog`:

```json theme={null}
{ "merchant_id": "mrc_walmart", "query": "AA batteries" }
```

It gets back up to 10 products. This is a real response, trimmed to two items:

```json theme={null}
{
  "test_mode": true,
  "merchant_id": "mrc_walmart",
  "query": "AA batteries",
  "items": [
    {
      "merchant_id": "mrc_walmart",
      "product_id": "ps8ZD3V",
      "title": "High Energy AA Batteries",
      "brand": "Rayovac",
      "price": 16.97,
      "currency": "USD",
      "availability": "InStock",
      "url": "https://buy.trychannel3.com/ps8ZD3V-...",
      "image_url": "https://cdn.trychannel3.com/..."
    },
    {
      "merchant_id": "mrc_walmart",
      "product_id": "xonuqtF",
      "title": "Max AA Batteries",
      "brand": "Energizer",
      "price": 4.97,
      "currency": "USD",
      "availability": "InStock",
      "url": "https://buy.trychannel3.com/xonuqtF-...",
      "image_url": "https://cdn.trychannel3.com/..."
    }
  ]
}
```

To get one product, call `get_product` with the same `merchant_id` and a `product_id` from the results.

> [!TIP]
>
> Search returns the closest matches it has, not only exact ones. Lower results can be a different
> size or an accessory, such as AAA batteries in an AA search. Have your agent check each title
> before it uses a result.

## What test mode covers

| Works with no key | Needs a test key |
| - | - |
| `search_catalog` and `get_product` at Walmart (`mrc_walmart`) | Every other tool: carts, checkout, payments, orders and returns |

Every tool is listed, so your agent can see the full API. Tools outside test mode return `needs_test_key`.

## Errors your agent may see

| Code | What it means | What to do |
| - | - | - |
| `needs_test_key` | The tool needs a test key. | Stop and tell the user. Retrying won't help. |
| `merchant_not_in_test_mode` | Test mode only covers Walmart. | Use `merchant_id` `mrc_walmart`. |
| `rate_limited` | Too many searches from your address. Test mode allows 5 a minute and 10 a day. | Wait `retry_after_seconds`, then retry. |
| `daily_limit_reached` | Test mode has used today's search allowance. | Wait `retry_after_seconds`, then retry. |
| `provider_unavailable` | The catalog source is down or slow. | Wait `retry_after_seconds`, then retry. |
| `product_not_found` | No Walmart product has that `product_id`. | Search again and use an id from the results. |

Every error has a `code` and a `message`. The ones you can retry also have `retry_after_seconds`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.