MCP Server Quickstart

The Owning MCP (Model Context Protocol) server lets any MCP-compatible AI client — Claude Desktop, GPT, Cursor, or any custom agent — search, browse, create, and manage listings on Owning.pro without writing HTTP code. It wraps the REST API in 10 simple tools exposed over JSON-RPC 2.0.

What is the MCP Server?

The MCP server is a thin layer that translates MCP protocol requests into HTTP calls to the Owning REST API. Instead of constructing HTTP requests with headers, URLs, and JSON bodies, an AI agent simply calls a tool like search_listings or create_listing with structured arguments.

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)

Connecting to the MCP Server

Server URL

Protocol

The server implements the MCP Streamable HTTP transport (spec 2025-03-26). Each POST /mcp request is a complete JSON-RPC 2.0 request → response cycle. No persistent connection is needed.

Authentication

Pass your Owning API key as a Bearer token in the Authorization header:

Authorization: Bearer own_aBcD123eFgH456iJkL789mNoP012qRsT345uVwX678yZ

• Read tools (search, get, categories, asset types) — API key optional. Without a key, requests are anonymous (subject to public rate limits: 100 req/min per IP).
• Write tools (create, upload, publish, manage) — API key required with write permission.
• contact_seller — API key optional (public endpoint, rate limited per IP).

Step 1: Initialize

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

Step 2: List available tools

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

Step 3: Call a tool

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

Read Tools (5)

Read-only tools for searching and browsing listings. API key is optional — without one, requests are anonymous.

1. search_listings

Search for listings with filters. Returns matching listings with title, price, location, images, and key attributes.

Parameters

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

2. get_listing

Get full details of a specific listing by ID or slug. Returns all available information including description, specifications, all images, pricing, location, and attributes.

Parameters

3. get_listing_markdown

Get a listing in Markdown format — optimized for agents and AI consumption. Includes all listing data (title, price, description, specifications, images, attributes) in a structured, readable Markdown document with YAML frontmatter.

Parameters

# 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

List all available categories on Owning.pro with their listing counts. Returns a hierarchical tree of categories (parent and subcategories) with slug names and item counts. No parameters required.

5. get_asset_type

Get the attribute template for a specific category. Shows what fields/attributes are available for listings in that category (e.g. brand, model, year, length for boats).

Parameters

Write Tools (5)

Write tools for creating, publishing, and managing listings. All require an API key with write permission, except contact_seller which is public.

6. create_listing

Create a new listing on Owning.pro. The listing is created in draft status — use publish_listing to make it visible publicly. Rate limit: 10 listings per day per user.

Parameters

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

Upload an image to Owning.pro. Pass the image as base64-encoded data. If listing_id is provided, the image is attached to that listing (requires ownership). If omitted, a standalone upload returns a URL for use in create_listing. Rate limit: 50 images per day. Supported formats: jpg, png, webp, heic, heif, avif. Max size: 10 MB.

Parameters

8. publish_listing

Publish a draft listing, making it publicly visible on Owning.pro. Moves the listing from draft to active status. Only the listing owner can publish.

Parameters

9. contact_seller

Contact the seller of a listing by sending a message. The seller's email is never exposed — the API relays the message via email and the seller can reply to your email. No API key required (public endpoint). Rate limit: 5 contacts per hour per IP.

Parameters

10. manage_listing

Manage an existing listing — update its fields, change its status, or delete it. Only the listing owner can perform these actions. Supports three actions:

Parameters

# 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

The MCP server forwards all requests to the Owning REST API, so the API's rate limits apply:

Error Handling

Tool errors are returned as MCP results with isError: true and an error message in the content:

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

Invalid arguments (schema validation failures) are also returned as isError results with a description of which fields failed.

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