Connect Partle to your AI¶

Give your AI assistant direct access to Partle's live marketplace of products and local stores. Call get_stats for the current catalogue and store coverage; public catalogue reads need no account or API key.

MCP Server URL

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

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

Partle is listed in the official MCP Registry. The registry entry links to the public server repository and the remote endpoint above.

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¶

30 tools total — 6 public reads, 14 catalog/inventory operations, 1 feedback tool, and 9 OAuth-only account tools.

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 catalog/inventory write tools. 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).

Account preferences and security (OAuth only)¶

These tools act only on the account identified by the OAuth bearer token. API keys cannot call them. The four account permissions are not included in the normal catalog/inventory grant; explicitly request the required scope and approve it on the consent screen. Existing access and refresh tokens keep their previous permissions. If a client cannot request additional scopes, these tools remain unavailable to that client until it supports that authorization flow.

Tool	Required permission	Behavior
`get_account_settings`	`account:read`	Read your account ID, email, username and theme.
`update_account_settings`	`account:write`	Set theme to `light`, `dark`, or `system`.
`set_account_username`	`account:write`	Set an unset username once, using the website's existing rules.
`list_account_api_keys`	`security:read`	List key IDs, labels, prefixes and dates, without secrets.
`create_account_api_key`	`security:write`	Create a key and return its secret once.
`rotate_account_api_key`	`security:write`	Create a replacement and leave the old key active.
`revoke_account_api_key`	`security:write`	Immediately invalidate one of your keys.
`list_connected_apps`	`security:read`	List active app grants and all their active permissions.
`revoke_connected_app`	`security:write`	Revoke the app's access and refresh tokens for your account.

Credential permissions are powerful. security:write lets an app mint keys with full catalog and inventory access, regardless of its narrower OAuth scopes. Those keys still cannot use these account-management tools. Grant this permission only to an app you trust to manage credentials. Never publish returned secrets.

For rotation: call rotate_account_api_key, securely install the replacement, test the consumer, then call revoke_account_api_key with previous_key_id. Rotation is not complete until the old key is revoked. Each create/rotate call creates a new key; after a lost response, inspect the key list rather than blindly retrying. Revoking the calling app disconnects it on its next request.

Account theme changes appear on the website at login, reload or window focus. An unset account theme is returned as null and preserves the browser's existing choice. Guest choices remain local. Passwords, sign-in provider changes, profile pictures and account deletion remain website operations.

Catalog and inventory tools¶

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: name, 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: current product and store totals returned by get_stats.
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.

Tools are missing arguments or failing with schema errors?

Long-running AI conversations (like on claude.ai) cache the tool list per conversation. If Partle recently updated its MCP schema, you must start a fresh conversation for your AI to see the new tool definitions.

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)