MCP-Server Schnellstart

Der Owning MCP (Model Context Protocol) Server ermöglicht es jedem MCP-kompatiblen KI-Client – Claude Desktop, GPT, Cursor oder jedem benutzerdefinierten Agenten – Anzeigen auf Owning.pro zu suchen, zu durchsuchen, zu erstellen und zu verwalten, ohne HTTP-Code zu schreiben. Er umschließt die REST API in 10 einfachen Tools, die über JSON-RPC 2.0 bereitgestellt werden.

Was ist der MCP-Server?

Der MCP-Server ist eine dünne Schicht, die MCP-Protokoll-Anfragen in HTTP-Aufrufe an die Owning REST API übersetzt. Anstatt HTTP-Anfragen mit Headern, URLs und JSON-Bodys zu konstruieren, ruft ein KI-Agent einfach ein Tool wie search_listings oder create_listing mit strukturierten Argumenten auf.

Architektur

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)

Verbindung zum MCP-Server

Server-URL

Protokoll

Der Server implementiert den MCP Streamable HTTP-Transport (Spezifikation 2025-03-26). Jede POST /mcp-Anfrage ist ein vollständiger JSON-RPC 2.0 Anfrage-→-Antwort-Zyklus. Es ist keine dauerhafte Verbindung erforderlich.

Authentifizierung

Übergib deinen Owning API-Schlüssel als Bearer-Token im Authorization-Header:

Authorization: Bearer own_aBcD123eFgH456iJkL789mNoP012qRsT345uVwX678yZ

• Lese-Tools (search, get, categories, asset types) – API-Schlüssel optional. Ohne Schlüssel sind Anfragen anonym (unterliegen öffentlichen Rate-Limits: 100 Anfragen/Min pro IP).
• Schreib-Tools (create, upload, publish, manage) – API-Schlüssel mit Schreibberechtigung erforderlich.
• contact_seller – API-Schlüssel optional (öffentlicher Endpoint, Rate-Limit pro IP).

Schritt 1: Initialisieren

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

Schritt 2: Verfügbare Tools auflisten

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

Schritt 3: Ein Tool aufrufen

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

Lese-Tools (5)

Schreibgeschützte Tools zum Suchen und Durchsuchen von Anzeigen. API-Schlüssel ist optional – ohne einen sind Anfragen anonym.

1. search_listings

Suche nach Anzeigen mit Filtern. Gibt übereinstimmende Anzeigen mit Titel, Preis, Standort, Bildern und wichtigsten Attributen zurück.

Parameter

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

2. get_listing

Rufe alle Details einer bestimmten Anzeige nach ID oder Slug ab. Gibt alle verfügbaren Informationen einschließlich Beschreibung, Spezifikationen, allen Bildern, Preisen, Standort und Attributen zurück.

Parameter

3. get_listing_markdown

Rufe eine Anzeige im Markdown-Format ab – optimiert für Agenten und KI-Konsum. Enthält alle Anzeigedaten (Titel, Preis, Beschreibung, Spezifikationen, Bilder, Attribute) in einem strukturierten, lesbaren Markdown-Dokument mit YAML-Frontmatter.

Parameter

# 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

Liste alle verfügbaren Kategorien auf Owning.pro mit ihren Anzeigezahlen auf. Gibt einen hierarchischen Baum von Kategorien (übergeordnete und Unterkategorien) mit Slug-Namen und Artikelzahlen zurück. Keine Parameter erforderlich.

5. get_asset_type

Rufe die Attributvorlage für eine bestimmte Kategorie ab. Zeigt, welche Felder/Attribute für Anzeigen in dieser Kategorie verfügbar sind (z. B. Marke, Modell, Jahr, Länge für Boote).

Parameter

Schreib-Tools (5)

Schreib-Tools zum Erstellen, Veröffentlichen und Verwalten von Anzeigen. Alle erfordern einen API-Schlüssel mit Schreibberechtigung, außer contact_seller, das öffentlich ist.

6. create_listing

Erstelle eine neue Anzeige auf Owning.pro. Die Anzeige wird im Entwurfsstatus erstellt – verwende publish_listing, um sie öffentlich sichtbar zu machen. Rate-Limit: 10 Anzeigen pro Tag pro Benutzer.

Parameter

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

Lade ein Bild auf Owning.pro hoch. Übergib das Bild als base64-kodierte Daten. Wenn listing_id angegeben wird, wird das Bild an diese Anzeige angehängt (erfordert Eigentümerschaft). Wenn weggelassen, gibt ein eigenständiger Upload eine URL zurück, die in create_listing verwendet werden kann. Rate-Limit: 50 Bilder pro Tag. Unterstützte Formate: jpg, png, webp, heic, heif, avif. Maximale Größe: 10 MB.

Parameter

8. publish_listing

Veröffentliche eine Entwurfsanzeige und mache sie öffentlich auf Owning.pro sichtbar. Verschiebt die Anzeige vom Entwurfs- in den aktiven Status. Nur der Anzeigeneigentümer kann veröffentlichen.

Parameter

9. contact_seller

Kontaktiere den Verkäufer einer Anzeige, indem du eine Nachricht sendest. Die E-Mail-Adresse des Verkäufers wird nie offengelegt – die API leitet die Nachricht per E-Mail weiter und der Verkäufer kann auf deine E-Mail antworten. Kein API-Schlüssel erforderlich (öffentlicher Endpoint). Rate-Limit: 5 Kontakte pro Stunde pro IP.

Parameter

10. manage_listing

Verwalte eine bestehende Anzeige – aktualisiere ihre Felder, ändere ihren Status oder lösche sie. Nur der Anzeigeneigentümer kann diese Aktionen durchführen. Unterstützt drei Aktionen:

Parameter

# 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

Der MCP-Server leitet alle Anfragen an die Owning REST API weiter, daher gelten die Rate-Limits der API:

Fehlerbehandlung

Tool-Fehler werden als MCP-Ergebnisse mit isError: true und einer Fehlermeldung im Inhalt zurückgegeben:

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

Ungültige Argumente (Schema-Validierungsfehler) werden ebenfalls als isError-Ergebnisse mit einer Beschreibung zurückgegeben, welche Felder fehlgeschlagen sind.

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