Démarrage rapide du serveur MCP

Le serveur MCP (Model Context Protocol) d'Owning permet à tout client IA compatible MCP — Claude Desktop, GPT, Cursor ou tout agent personnalisé — de rechercher, parcourir, créer et gérer des annonces sur Owning.pro sans écrire de code HTTP. Il encapsule l'API REST dans 10 outils simples exposés via JSON-RPC 2.0.

Qu'est-ce que le serveur MCP ?

Le serveur MCP est une couche légère qui traduit les requêtes du protocole MCP en appels HTTP vers l'API REST d'Owning. Au lieu de construire des requêtes HTTP avec des en-têtes, des URL et des corps JSON, un agent IA appelle simplement un outil comme search_listings ou create_listing avec des arguments structurés.

Architecture

MCP Client (Claude Desktop, GPT, Cursor, custom agent)
  |  MCP protocol (JSON-RPC 2.0 over HTTP)
  v
MCP Server (https://mcp.owning.pro)
  |  HTTP calls to api.owning.pro
  v
Owning API (https://api.owning.pro)

Connexion au serveur MCP

URL du serveur

Protocole

Le serveur implémente le transport MCP Streamable HTTP (spec 2025-03-26). Chaque requête POST /mcp est un cycle complet de requête → réponse JSON-RPC 2.0. Aucune connexion persistante n'est nécessaire.

Authentification

Passez votre clé API Owning en tant que token Bearer dans l'en-tête Authorization :

Authorization: Bearer own_aBcD123eFgH456iJkL789mNoP012qRsT345uVwX678yZ

• Outils de lecture (recherche, consultation, catégories, types d'actifs) — clé API facultative. Sans clé, les requêtes sont anonymes (soumises aux limites de débit publiques : 100 req/min par IP).
• Outils d'écriture (création, téléversement, publication, gestion) — clé API requise avec permission d'écriture.
• contact_seller — clé API facultative (endpoint public, limité par IP).

Étape 1 : Initialiser

curl -X POST https://mcp.owning.pro/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

# Response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "owning-mcp", "version": "0.2.0" }
  }
}

Étape 2 : Lister les outils disponibles

curl -X POST https://mcp.owning.pro/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# Response: array of 10 tool definitions with name, description, and inputSchema

Étape 3 : Appeler un outil

curl -X POST https://mcp.owning.pro/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer own_aBcD123eFgH..." \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_listings",
      "arguments": {
        "query": "bavaria",
        "category": "boats",
        "limit": 5
      }
    }
  }'

# Response:
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{ \"results\": [...], \"pagination\": {...} }" }]
  }
}

Outils de lecture (5)

Outils en lecture seule pour rechercher et parcourir des annonces. La clé API est facultative — sans clé, les requêtes sont anonymes.

1. search_listings

Rechercher des annonces avec des filtres. Renvoie les annonces correspondantes avec titre, prix, localisation, images et attributs clés.

Paramètres

# Example: search for Bavaria boats under 150k
{
  "name": "search_listings",
  "arguments": {
    "query": "bavaria",
    "category": "boats",
    "max_price": 150000,
    "limit": 10
  }
}

2. get_listing

Obtenir les détails complets d'une annonce spécifique par ID ou slug. Renvoie toutes les informations disponibles, y compris la description, les spécifications, toutes les images, les prix, la localisation et les attributs.

Paramètres

3. get_listing_markdown

Obtenir une annonce au format Markdown — optimisé pour les agents et la consommation par l'IA. Inclut toutes les données de l'annonce (titre, prix, description, spécifications, images, attributs) dans un document Markdown structuré et lisible avec un frontmatter YAML.

Paramètres

# Example response content:
---
title: "Lagoon 400 S2"
price: 295000
currency: "EUR"
condition: "good"
---

## Description
Gebrauchtboot; Baujahr 2016

## Specifications
- **Brand**: lagoon
- **Year**: 2016
- **Length**: 11.97 m

4. list_categories

Lister toutes les catégories disponibles sur Owning.pro avec leur nombre d'annonces. Renvoie un arbre hiérarchique de catégories (parent et sous-catégories) avec les noms de slug et les nombres d'éléments. Aucun paramètre requis.

5. get_asset_type

Obtenir le modèle d'attributs pour une catégorie spécifique. Indique quels champs/attributs sont disponibles pour les annonces dans cette catégorie (par ex. marque, modèle, année, longueur pour les bateaux).

Paramètres

Outils d'écriture (5)

Outils d'écriture pour créer, publier et gérer des annonces. Tous nécessitent une clé API avec permission d'écriture, à l'exception de contact_seller qui est public.

6. create_listing

Créer une nouvelle annonce sur Owning.pro. L'annonce est créée avec le statut brouillon — utilisez publish_listing pour la rendre visible publiquement. Limite de débit : 10 annonces par jour et par utilisateur.

Paramètres

{
  "name": "create_listing",
  "arguments": {
    "title": "Apple iPhone 13 128GB Blue",
    "description": "Apple iPhone 13 in blue, 128GB. Good condition, battery health 89%.",
    "category_id": "electronics",
    "condition": "good",
    "price": { "amount": 399, "currency": "EUR", "negotiable": true },
    "location": { "country": "ES", "city": "Madrid", "shipping": true },
    "tags": ["iphone", "apple", "smartphone"]
  }
}

7. upload_image

Téléverser une image sur Owning.pro. Passez l'image en tant que données encodées en base64. Si listing_id est fourni, l'image est attachée à cette annonce (nécessite la propriété). Si omis, un téléversement autonome renvoie une URL à utiliser dans create_listing. Limite de débit : 50 images par jour. Formats pris en charge : jpg, png, webp, heic, heif, avif. Taille maximale : 10 Mo.

Paramètres

8. publish_listing

Publier une annonce brouillon, la rendant visible publiquement sur Owning.pro. Fait passer l'annonce du statut brouillon au statut actif. Seul le propriétaire de l'annonce peut la publier.

Paramètres

9. contact_seller

Contacter le vendeur d'une annonce en envoyant un message. L'email du vendeur n'est jamais exposé — l'API relaie le message par email et le vendeur peut répondre à votre email. Aucune clé API requise (endpoint public). Limite de débit : 5 contacts par heure et par IP.

Paramètres

10. manage_listing

Gérer une annonce existante — mettre à jour ses champs, changer son statut ou la supprimer. Seul le propriétaire de l'annonce peut effectuer ces actions. Prend en charge trois actions :

Paramètres

# Example: pause a listing
{
  "name": "manage_listing",
  "arguments": {
    "id_or_slug": "apple-iphone-13-128gb-blue",
    "action": "change_status",
    "status": "paused"
  }
}

# Example: update the price
{
  "name": "manage_listing",
  "arguments": {
    "id_or_slug": "apple-iphone-13-128gb-blue",
    "action": "update",
    "price": { "amount": 350, "currency": "EUR", "negotiable": false }
  }
}

# Example: delete a listing
{
  "name": "manage_listing",
  "arguments": {
    "id_or_slug": "apple-iphone-13-128gb-blue",
    "action": "delete"
  }
}

Limites de débit

Le serveur MCP transfère toutes les requêtes à l'API REST d'Owning, donc les limites de débit de l'API s'appliquent :

Gestion des erreurs

Les erreurs d'outil sont renvoyées en tant que résultats MCP avec isError: true et un message d'erreur dans le contenu :

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{ "type": "text", "text": "Search failed: Rate limit exceeded (status 429)" }],
    "isError": true
  }
}

Les arguments invalides (échecs de validation du schéma) sont également renvoyés en tant que résultats isError avec une description des champs en échec.

Vérification de l'état

curl https://mcp.owning.pro/health

# Response:
{
  "status": "ok",
  "service": "owning-mcp",
  "version": "0.2.0",
  "timestamp": "2026-07-11T16:17:44.333Z",
  "apiBaseUrl": "https://api.owning.pro",
  "tools": [
    "search_listings", "get_listing", "get_listing_markdown",
    "list_categories", "get_asset_type",
    "create_listing", "upload_image", "publish_listing",
    "contact_seller", "manage_listing"
  ]
}