Connect Partle to your AI¶

Give your AI assistant direct access to 130,000+ products across ~16,000 local stores. No account, no API key, no setup beyond pasting a URL.

MCP Server URL

https://partle.rubenayla.xyz/mcp/

Transport: Streamable HTTP (MCP spec 2025-06-18). Auto-discovery at /.well-known/mcp.json.

Supported clients¶

Claude Code CLI

One line in your terminal. The fastest path.

Setup
Claude Desktop & claude.ai

Add a custom connector in Settings.

Setup
Any MCP client

Generic install for spec-compliant clients.

Setup

Other clients

Cursor, VS Code Copilot, ChatGPT custom connectors, and Windsurf should all work with the generic URL above, but we haven't verified them end-to-end. If you get one running, open an issue — we'll add it here.

Setup¶

Claude Code CLI¶

Run this once:

claude mcp add --transport http partle https://partle.rubenayla.xyz/mcp/

Then restart Claude Code. Partle tools appear in the tool picker.

Claude Desktop & claude.ai¶

Open Settings → Connectors (claude.ai) or the Connectors pane in Claude Desktop.
Click Add custom connector.
Paste the server URL:
```
https://partle.rubenayla.xyz/mcp/
```
Save. Partle tools appear in any chat.

Any MCP client¶

Point your client at the Streamable HTTP endpoint. Most clients accept either a URL field or a JSON config:

mcp.json

{
  "mcpServers": {
    "partle": {
      "url": "https://partle.rubenayla.xyz/mcp/"
    }
  }
}

Auto-discovery manifest: https://partle.rubenayla.xyz/.well-known/mcp.json.

Available tools¶

21 tools total — 6 read (no auth), 14 write (OAuth or API key), 1 feedback.

Read (no auth required)¶

Tool	Description
`search_products`	Search by name or description. Filters: price range, tags, store, sort order. Optional semantic (vector) search for cross-language matching.
`get_product`	Full details for a product by ID.
`search_stores`	Search or list stores by name/address.
`get_store`	Full details for a store by ID.
`get_stats`	Platform statistics — total products and stores.
`search_wanted`	Browse public buy requests at `/wanted` — things people are looking for but haven't found. Useful for AI agents that want to offer matches: cross-reference open requests against `search_products`, surface hits.

Write (authenticated)¶

Two ways to authenticate, in preference order:

OAuth (recommended) — when you add Partle as a custom connector in claude.ai, ChatGPT, Cursor, or any MCP client that supports OAuth, the client walks you through a one-click consent screen ("Allow Claude to read and edit your Partle products?") and attaches a bearer token automatically on every write call. No password or key in chat. Revoke at partle.rubenayla.xyz/account → Connected apps. Scopes: products:read, products:write, inventory:read, inventory:write.
API key (fallback) — pass an api_key parameter to any write tool. Generate at partle.rubenayla.xyz/account → API Keys. Keys start with pk_. Use this when your client doesn't support OAuth (e.g. raw scripts, programmatic agents).

Products — public catalog listings.

Tool	Description
`create_product`	Create a new product listing. Set `verified=false` when an AI agent is proposing a listing on behalf of a user who hasn't confirmed it (tentative).
`update_product`	Update fields on an existing product.
`delete_product`	Permanently delete a product and its images.
`upload_product_image`	Attach an image via signed upload URL.
`delete_product_image`	Remove a specific image from a product.
`get_my_products`	List products created by the authenticated user.
`get_upload_url`	Get a signed URL for attaching an image to a product created earlier.

Inventory — the user's private workshop tracking (owned / wanted / for_sale / sold / discarded). Private to the owner; does not appear on the public buy-requests feed.

Tool	Description
`get_my_inventory`	List the caller's inventory items. Filter by status, project, free text.
`add_inventory_item`	Add a row covering any lifecycle state.
`update_inventory_item`	Patch any field on an existing row.
`delete_inventory_item`	Permanently remove a row.
`mark_for_sale`	Convenience: flip an `owned` item to `for_sale` and set the asking price.
`mark_sold`	Convenience: flip a `for_sale` item to `sold`.

Buy requests — public demand-side posts shown on /wanted. Independent of personal inventory.

Tool	Description
`create_buy_request`	Post a public buy request. Sales-facing ad: title, description, quantity, optional `max_price`, optional `contact` (email/phone/handle shown publicly so suppliers can reach you outside the platform).

OAuth metadata for clients that probe for it:

Protected resource metadata: /.well-known/oauth-protected-resource (RFC 9728)
Authorization server metadata: /.well-known/oauth-authorization-server (RFC 8414)
Endpoints: /oauth/authorize, /oauth/token, /oauth/register (DCR), /oauth/revoke. PKCE S256 required. Resource indicator: https://partle.rubenayla.xyz/mcp (RFC 8707).

Feedback¶

Tool	Description
`submit_feedback`	Send us freeform feedback about your integration experience.

Example queries¶

Once connected, try asking your AI. Three end-to-end walk-throughs below use real data returned by the production server.

Example 1 — find affordable drills¶

You: "Use Partle to search for a drill under €50."

Claude (calls search_products with query="drill", max_price=50) → real response includes:

Blackspur 13pc High Speed Drill Bit Set — €4.99 at Lenehans (IE). Hardened/tempered bits, 1.5–6.5 mm, for metal/wood/plastic. → link
Flotec FPDMP21SA Drill Pump 225 GPH — €17.14 at Kooyman Megastore Zeelandia. Thermoplastic pump that chucks into any drill ≥1200 RPM, uses standard garden hoses. → link
Concrete Drill 6×100 mm Stalco Perfect S-71310 — €1.49 at My Home Tools (Kirkcaldy, GB). Carbide head for impact drills. → link

The response includes a canonical partle_url for every product so the AI can link directly to the listing.

Example 2 — cross-language semantic search¶

You: "Find products related to 'cerrojo' on Partle, even if the listing is in another language."

Claude (calls search_products with query="cerrojo", semantic=true) → returns lock and bolt products from listings written in English, Spanish, German, and Dutch. Useful when the user knows the Spanish term for a part but the merchant's listing is in another language. Without semantic=true, only exact-match Spanish listings would be returned.

Example 3 — platform stats and store discovery¶

You: "How big is the Partle marketplace, and what stores does it cover near Madrid?"

Claude (calls get_stats then search_stores with query="Madrid") → returns:

Stats: ~131,000 products across ~16,000 stores.
A list of stores with addresses in or near Madrid (ferreterias, hardware shops, second-hand listings) with their store IDs that can be fed back into search_products via store_id.

Example 4 — write flow with an API key¶

You: "Add a product on Partle called 'Cherry MX Brown switches, pack of 10', €18, to my personal listings. My API key is pk_…."

Claude (calls create_product with the API key as a tool parameter) → returns the new product's ID and partle_url. Errors out with a clear message if the key is invalid or expired. The same key works for update_product, delete_product, upload_product_image, and get_my_products.

API key handling

Pasting an API key into chat is fine for personal use, but treat it like a password — don't share screenshots showing the full key. You can revoke and regenerate at /account at any time.

Auth & rate limits¶

Access	Auth	Rate limit
Public read (`search_products`, `get_product`, `search_stores`, `get_store`, `get_stats`)	None	100 req/hr per `Mcp-Session-Id` (IP fallback)
Authenticated read (`get_my_products`)	OAuth bearer with `products:read` scope, OR `api_key`	Same
Write (create, update, delete, image upload/delete)	OAuth bearer with `products:write` scope, OR `api_key`	Same
Feedback (`submit_feedback`)	None	100 req/hr per IP
OAuth `/oauth/authorize`	n/a	60/hr per IP
OAuth `/oauth/token` (refresh, exchange)	n/a	1000/hr per IP

Troubleshooting¶

Tools don't appear after adding the connector

Restart the client. Some clients (Claude Code, Cursor) cache the tool list on startup.

401 or 403 on write tools

If you're using OAuth: re-add the connector from your AI client (the consent flow may have failed silently). Or, check the Connected apps section at /account to confirm the grant exists. If you're using an API key: regenerate it at /account — keys start with pk_.

How do I revoke an AI's access?

For OAuth: open /account → Connected apps → click Revoke. The token stops working within seconds. For API key: same page → API Keys → Revoke.

Rate-limited

Public read access is capped at 100 req/hr per IP. Space out bulk calls or use pagination (limit + offset).

Something else broken?

Use the submit_feedback tool directly from your AI, open an issue, or email [email protected].

Support¶

Email: [email protected]
MCP feedback tool: submit_feedback (call from any connected client)
GitHub issues: github.com/rubenayla/partle-mcp/issues
Privacy / data-rights requests: same email (response within 30 days)
Security disclosures: same email (acknowledgement within 5 business days, breach disclosure within 72h)