SecretBox MCP — Documentation
Version 4.4.0 · Édité par API & YOU
À propos
SecretBox MCP est un connecteur Model Context Protocol qui permet à Claude.ai de rechercher des coffrets cadeaux d’expériences gastronomiques (restaurants étoilés, hôtels, dégustations…) dans le catalogue SecretBox, et d’afficher les résultats sous forme de carte interactive et de fiches détaillées.
- « Trouve-moi un coffret cadeau gastronomique près de Lyon, max 200 € »
- « Quels coffrets dégustation chez un chef étoilé Michelin en Bourgogne ? »
- « Détaille-moi le coffret Soirée gourmande du chef X »
- « Une expérience hôtelière 5★ dans le Var pour deux personnes »
Connexion à Claude.ai
https://mcp-claude.api-and-you.com/mcpExemples d’usage
Recherche simple
User : Je cherche un coffret cadeau gourmand pour deux personnes
à Bordeaux, max 150 €.
Claude (utilise search_item) : Voici 3 coffrets correspondants…
[carte interactive + 3 cards]Recherche multilingue
User : I'd like a gift experience near Nice, around 100 euros.
Claude (search_item, query traduit en FR, locale=en_US) :
Here are 4 experiences near Nice…Le texte de la requête est traduit en français avant interrogation (le catalogue est indexé en FR), mais la réponse de Claude reste dans la langue de l’utilisateur.
Détail d’un coffret
User : Donne-moi plus d'infos sur le coffret SBX-12345.
Claude (utilise get_item) : Coffret « Dîner gastronomique »
chez le chef Pierre Dupont, 2 étoiles Michelin…
[fiche détail interactive]Outils MCP exposés
| Nom | Title | Type | Description courte |
|---|---|---|---|
search_item |
Search SecretBox catalog | Read-only | Recherche multilingue dans le catalogue avec filtres. |
get_item |
Get SecretBox experience details | Read-only | Récupère le détail complet d’une expérience par global_id. |
search_item
Recherche structurée avec score de pertinence et déduplication par établissement.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
query | string (FR) | oui | Texte de recherche, en français. |
locale | string | non | fr_FR, en_US, es_ES, it_IT, de_DE. Défaut : fr_FR. |
limit | number | non | 1–8. Défaut : 4. |
filters.productType | "box" | "giftcard" | "article" | non | Type de produit. |
filters.city | string | non | Filtre par ville. |
filters.region | string | non | Filtre par région. |
filters.department | string | non | Département français (ex: « Jura »). |
filters.priceMax | number | non | Prix maximum en euros. |
filters.deliveryMode | "mail" | "email" | "onsite" | non | Mode de livraison. |
filters.geo | object | non | { lat, lon, radius } pour recherche de proximité. |
get_item
Récupère un coffret par son identifiant global.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
global_id | string | oui | Identifiant unique du coffret. |
Widgets affichés
Les deux outils déclenchent automatiquement un widget interactif (extension MCP Apps), affiché dans une iframe sandboxée à l’intérieur de la conversation Claude :
- Catalog widget (sur
search_item) : carte Leaflet centrée sur les établissements + slider de cards défilables, panneau de détail latéral. - Item detail widget (sur
get_item) : fiche complète avec hero image, distinctions gastronomiques, classement hôtelier, bouton de réservation.
Les images et fonds cartographiques sont pré-fetchés côté serveur et embarqués en data: URI dans la réponse, pour respecter la CSP connect-src 'self' de l’iframe Claude.
Authentification
OAuth 2.1 conforme aux RFC 8414 (Authorization Server Metadata), 9728 (Protected Resource Metadata) et 7591 (Dynamic Client Registration), avec PKCE S256.
| Endpoint | RFC |
|---|---|
/.well-known/oauth-authorization-server | RFC 8414 |
/.well-known/oauth-protected-resource | RFC 9728 |
/register | RFC 7591 (DCR) |
/authorize | OAuth 2.1 |
/token | OAuth 2.1 + PKCE S256 |
Scope unique : mcp:tools. TTL access token : 24 h.
Limites & quotas
- limit max : 8 résultats par appel
search_item. - Filtre
geo: ne pas combiner aveccity(le filtre géographique prime). - OSM tiles : pré-fetch limité à un nombre raisonnable de niveaux de zoom (overview + 8 niveaux par marker). Les niveaux intermédiaires sont reconstruits par fallback ancestor côté widget.
- Images : redimensionnées à 400 px max de largeur, format WebP qualité 55. Les images sources non disponibles sont silencieusement omises.
Erreurs courantes
| Code | Message | Cause | Résolution |
|---|---|---|---|
| 403 | origin_not_allowed | Origin-header absent de la whitelist. | Appel via Claude.ai ou MCP Inspector uniquement. |
| -32601 | Method not found | Méthode JSON-RPC inconnue. | Voir liste : initialize, tools/list, tools/call, resources/list, resources/read, ping. |
| -32602 | Invalid arguments | Paramètres outil invalides (Zod schema). | Vérifier le type/nom des paramètres. |
| 500 | Erreur Elasticsearch | ES indisponible ou index manquant. | Vérifier /health, contacter le support. |
Changelog
v4.4.0 — 28 avril 2026
- Ajout du
titleannotation sur les deux outils (conformité Anthropic). - Validation Origin-header sur
/mcp. - Logs durcis : la query texte n’apparaît plus en stderr (longueur seule).
- Privacy Policy publiée sous
/privacy. - Documentation publique publiée sous
/docs.
v4.3.x — précédentes
- Implémentation MCP Apps (widgets interactifs, structuredContent).
- Migration vers JSON-RPC plain (contournement de la troncature SSE Anthropic).
- OAuth 2.1 + PKCE complet pour Connectors Directory.
