Guida rapida MCP Server

Il server MCP (Model Context Protocol) di Owning consente a qualsiasi client IA compatibile con MCP — Claude Desktop, GPT, Cursor o qualsiasi agente personalizzato — di cercare, sfogliare, creare e gestire annunci su Owning.pro senza scrivere codice HTTP. Racchiude la REST API in 10 strumenti semplici esposti tramite JSON-RPC 2.0.

Cos'è il MCP Server?

Il server MCP è un livello sottile che traduce le richieste del protocollo MCP in chiamate HTTP alla REST API di Owning. Invece di costruire richieste HTTP con header, URL e corpi JSON, un agente IA semplicemente chiama uno strumento come search_listings or create_listing con argomenti strutturati.

Architettura

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)

Connessione al MCP Server

URL del server

Protocollo

Il server implementa il trasporto MCP Streamable HTTP (spec 2025-03-26). Ogni richiesta POST /mcp è un ciclo completo richiesta/risposta JSON-RPC 2.0. Non è necessaria una connessione persistente.

Autenticazione

Passa la tua API key Owning come Bearer token nell'header Authorization:

Authorization: Bearer own_aBcD123eFgH456iJkL789mNoP012qRsT345uVwX678yZ

• Strumenti di lettura (search, get, categories, asset types) — API key opzionale. Senza chiave, le richieste sono anonime (soggette ai limiti pubblici: 100 req/min per IP).
• Strumenti di scrittura (create, upload, publish, manage) — API key richiesta con permesso di scrittura.
• contact_seller — API key opzionale (endpoint pubblico, rate limit per IP).

Passo 1: Inizializza

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" }
  }
}

Passo 2: Elenca gli strumenti disponibili

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

Passo 3: Chiama uno strumento

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\": {...} }" }]
  }
}

Strumenti di lettura (5)

Strumenti di sola lettura per cercare e sfogliare annunci. L'API key è opzionale — senza, le richieste sono anonime.

1. search_listings

Cerca annunci con filtri. Restituisce annunci corrispondenti con titolo, prezzo, posizione, immagini e attributi chiave.

Parametri

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

2. get_listing

Ottieni i dettagli completi di un annuncio specifico per ID o slug. Restituisce tutte le informazioni disponibili inclusi descrizione, specifiche, tutte le immagini, prezzo, posizione e attributi.

Parametri

3. get_listing_markdown

Ottieni un annuncio in formato Markdown — ottimizzato per agenti e consumo IA. Include tutti i dati dell'annuncio (titolo, prezzo, descrizione, specifiche, immagini, attributi) in un documento Markdown strutturato e leggibile con frontmatter YAML.

Parametri

# 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

Elenca tutte le categorie disponibili su Owning.pro con i relativi conteggi di annunci. Restituisce un albero gerarchico di categorie (padre e sottocategorie) con nomi slug e conteggi elementi. Nessun parametro richiesto.

5. get_asset_type

Ottieni il template di attributi per una categoria specifica. Mostra quali campi/attributi sono disponibili per gli annunci in quella categoria (es. marca, modello, anno, lunghezza per le barche).

Parametri

Strumenti di scrittura (5)

Strumenti di scrittura per creare, pubblicare e gestire annunci. Tutti richiedono un'API key con permesso di scrittura, tranne contact_seller che è pubblico.

6. create_listing

Crea un nuovo annuncio su Owning.pro. L'annuncio viene creato in stato bozza — usa publish_listing per renderlo visibile pubblicamente. Rate limit: 10 annunci al giorno per utente.

Parametri

{
  "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

Carica un'immagine su Owning.pro. Passa l'immagine come dati codificati base64. Se viene fornito listing_id, l'immagine viene allegata a quell'annuncio (richiede proprietà). Se omesso, un caricamento autonomo restituisce un URL da usare in create_listing. Rate limit: 50 immagini al giorno. Formati supportati: jpg, png, webp, heic, heif, avif. Dimensione max: 10 MB.

Parametri

8. publish_listing

Pubblica un annuncio in bozza, rendendolo visibile pubblicamente su Owning.pro. Sposta l'annuncio dallo stato bozza ad attivo. Solo il proprietario dell'annuncio può pubblicare.

Parametri

9. contact_seller

Contatta il venditore di un annuncio inviando un messaggio. L'email del venditore non viene mai esposta — l'API inoltra il messaggio via email e il venditore può rispondere alla tua email. Nessuna API key richiesta (endpoint pubblico). Rate limit: 5 contatti all'ora per IP.

Parametri

10. manage_listing

Gestisci un annuncio esistente — aggiorna i campi, cambia lo stato o eliminalo. Solo il proprietario dell'annuncio può eseguire queste azioni. Supporta tre azioni:

Parametri

# 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"
  }
}

Rate Limits

Il server MCP inoltra tutte le richieste alla REST API di Owning, quindi si applicano i rate limit dell'API:

Gestione degli errori

Gli errori degli strumenti vengono restituiti come risultati MCP con isError: true e un messaggio di errore nel contenuto:

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

Anche gli argomenti non validi (fallimenti di validazione dello schema) vengono restituiti come risultati isError con una descrizione di quali campi hanno fallito.

Health Check

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"
  ]
}