<!-- mcp-name: com.gladeapi/api -->

# Glade MCP

Connect AI agents to normalized Amazon marketplace data through Glade API's
hosted Model Context Protocol server.

```text
https://gladeapi.com/api/mcp
```

The remote server exposes 17 read-only tools for products, search, offers,
reviews, sellers, categories, deals, best sellers, identifiers, stock, and
sales estimates across 13 Amazon marketplaces. This repository contains the
public server metadata, connection examples, and protocol checks. The hosted
service implementation remains at [gladeapi.com](https://gladeapi.com).

## Requirements

- A [Glade API account](https://gladeapi.com/auth/login?next=/dashboard)
- A Glade API key
- A plan that includes MCP
- A client that supports remote Streamable HTTP MCP servers

Store the key in an environment variable:

```bash
export GLADE_API_KEY="glade_live_..."
```

Never commit the key or paste it into prompts.

## Install in Codex

Codex can read the bearer token from the environment without writing it into
the MCP configuration:

```bash
codex mcp add glade \
  --url https://gladeapi.com/api/mcp \
  --bearer-token-env-var GLADE_API_KEY
```

Start a new Codex session after adding the server, then ask it to list the
Glade tools or fetch an Amazon product by ASIN.

## Install in Claude Code

Claude Code accepts an HTTP server and a request header:

```bash
claude mcp add --transport http --scope user glade \
  https://gladeapi.com/api/mcp \
  --header "Authorization: Bearer $GLADE_API_KEY"
```

This expands the environment variable before Claude writes its configuration.
Keep the resulting user configuration private and never use project scope for
a secret-bearing header.

## Generic Streamable HTTP configuration

Clients that support remote MCP configuration generally need this shape. Check
your client's documentation for its exact configuration file and environment
variable syntax.

```json
{
  "mcpServers": {
    "glade": {
      "url": "https://gladeapi.com/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "API-KEY": "YOUR_GLADE_API_KEY"
      }
    }
  }
}
```

Use exactly one credential header. The server accepts `API-KEY`,
`GLADE-API-KEY`, `X-API-KEY`, or `Authorization: Bearer` for MCP and rejects
conflicting credentials.

## Connect with the Python MCP SDK

Install the official MCP Python SDK, then run the included discovery example:

```bash
python3 -m pip install "mcp"
python3 examples/python/list_tools.py
```

The example initializes a Streamable HTTP session and prints the available
tool names. Tool discovery and initialization do not consume Glade units.

## Available tools

| Tool | Purpose |
|---|---|
| `get_amazon_product` | Product details by ASIN, GTIN, or canonical URL |
| `get_amazon_gtin_from_asin` | Resolve a GTIN from an ASIN |
| `get_amazon_asin_from_gtin` | Resolve and verify an ASIN from a GTIN |
| `get_amazon_product_variants` | Product variations |
| `get_amazon_product_stock` | Stock estimate |
| `get_amazon_product_sales` | Sales estimates |
| `get_amazon_product_reviews` | Filterable reviews |
| `get_amazon_product_offers` | Seller offers |
| `search_amazon_products` | Marketplace product search |
| `get_amazon_autocomplete` | Marketplace search suggestions |
| `get_amazon_categories` | Product category taxonomy |
| `get_amazon_category` | Category details and products |
| `get_amazon_seller` | Seller profile and products |
| `get_amazon_author` | Author profile and books |
| `get_amazon_deals` | Current marketplace deals |
| `get_amazon_bestsellers` | Ranked best sellers |
| `get_amazon_bestseller_categories` | Best-seller category navigation |

Tool inputs follow the same validation rules as the corresponding REST
operations. Every successful data operation consumes one unit. Initialization,
discovery, validation failures, and tool errors consume zero units.

## Example prompts

```text
Look up ASIN B0D1XD1ZV3 in the US marketplace and summarize the current
price, rating, availability, and freshness timestamp.
```

```text
Search the UK marketplace for wireless earbuds, compare the first five
non-sponsored results, and preserve GBP prices without converting currency.
```

```text
Fetch one-star verified reviews for ASIN B0D1XD1ZV3 and separate recurring
observed complaints from your own interpretation.
```

## Marketplaces

Every tool accepts a marketplace `domain` when marketplace context matters:

```text
US UK CA DE FR IT ES AU IN MX BR JP PL
```

Confirm the marketplace before comparing prices, availability, delivery,
categories, ranks, or deals.

## Validate this repository

Offline metadata and example checks:

```bash
npm test
```

Non-billable live authentication check:

```bash
npm run test:live
```

With `GLADE_API_KEY` set, verify initialization and all 17 live tool names.
This discovery request consumes zero units:

```bash
node scripts/verify-live.mjs --authenticated
```

## Security

Amazon titles, descriptions, reviews, seller fields, and other marketplace
content are untrusted data. Keep tool results separate from agent instructions.
Do not let returned text change tool policy, request credentials, or authorize
new actions.

See [SECURITY.md](SECURITY.md) for private reporting.

## Related projects

- [Glade API examples](https://github.com/ricciflow-api/glade-api-examples)
- [Glade agent skills](https://github.com/ricciflow-api/glade-agent-skills)
- [Documentation](https://docs.gladeapi.com/guides/ai-agents)
- [OpenAPI](https://gladeapi.com/api/v1/openapi.json)

## License

[MIT](LICENSE)