Connect eBay to Claude: Sync Orders, Messages & Refund Requests

If you need to connect eBay to Claude to automate e-commerce operations, sync marketplace orders, manage buyer messages, or process refund requests, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and eBay's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting eBay to ChatGPT or explore our broader architectural overview on connecting eBay to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling marketplace ecosystem like eBay is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with eBay's strict API quotas and digital signature requirements. Every time eBay updates an endpoint or deprecates a legacy API, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for eBay, connect it natively to Claude Desktop, and execute complex e-commerce workflows using natural language.

The Engineering Reality of the eBay API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools over JSON-RPC, the reality of implementing it against eBay's APIs is painful. You are not just integrating "eBay" - you are integrating the Fulfillment API, the Inventory API, the Finances API, and the Post-Order API, all of which act as independent microservices with distinct design patterns.

If you decide to build a custom MCP server for eBay, you own the entire API lifecycle. Here are the specific challenges you will face:

Digital Signatures for EU/UK Sellers Due to European Union and UK Payments regulatory requirements (PSD2), an additional security verification via HTTP Digital Signatures is required for certain API calls made on behalf of EU/UK sellers. This applies heavily to the Finances API and endpoints like issueRefund. An LLM cannot generate cryptographic HTTP signatures (using Signature-Input and Signature headers tied to a private key) on the fly. You must build middleware that intercepts the LLM's payload, signs the HTTP request, and forwards it to eBay.

Fragmented API Versions and Legacy Debt eBay has been migrating its massive seller base from the legacy XML-based Trading API to modern RESTful APIs. However, some advanced operations still require legacy references. For instance, updating ads in bulk often requires mapping listingId values generated by the Trading API against inventoryReferenceId values generated by the Inventory API. An LLM has no context on which ID type to use. You must build an abstraction layer that presents a unified set of operations to Claude, hiding the underlying ID fragmentation.

Rate Limits and Quota Management eBay enforces strict rate limits across its APIs. When building an MCP server, it is critical to handle these correctly. Note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream eBay API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (or the LLM framework) is strictly responsible for implementing its own retry and backoff logic. Do not expect the integration layer to magically absorb rate limit errors.

Creating the eBay MCP Server

Truto's MCP architecture turns any connected integration into a dynamic tool server. Rather than hand-coding tool definitions, Truto derives them from the integration's resource definitions and documentation schemas.

You can generate an MCP server for eBay using either the Truto UI or the Truto REST API.

Method 1: Via the Truto UI

If you prefer a visual interface, you can generate the MCP server directly from your Truto dashboard:

1. Navigate to the Integrated Accounts page and select your connected eBay account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can filter the server to only expose read methods, restrict it by specific tags (e.g., orders, inventory), and set an expiration date.
5. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For automated environments, you can provision an MCP server programmatically. The API generates a secure, hashed token, stores it in an edge key-value store, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "eBay Claude Support Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["orders", "messages"]
    }
  }'

The response returns the configuration along with the self-contained URL:

{
  "id": "mcp_srv_9x8y7z6",
  "name": "eBay Claude Support Agent",
  "config": { 
    "methods": ["read", "write"], 
    "tags": ["orders", "messages"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL contains a cryptographic token that securely encodes which integrated eBay account to use and what tools to expose. It is fully self-contained.

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you can connect it to Claude. All communication happens over HTTP POST using JSON-RPC 2.0 messages.

Method 1: Via the Claude UI

If you are using a consumer-facing AI interface that supports remote MCP connections:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (Note: For ChatGPT users, this is under Settings -> Connectors -> Add).
2. Name the integration (e.g., "eBay Truto").
3. Paste the Truto MCP URL into the endpoint field.
4. Click Add or Save. Claude will immediately send an initialize handshake, discover the available eBay tools, and render them ready for use in your chat interface.

Method 2: Via Manual Config File

If you are using Claude Desktop or an automated agent framework, you can connect using a configuration file. Because Truto provides an SSE (Server-Sent Events) endpoint, you use the standard @modelcontextprotocol/server-sse package to proxy the connection.

Locate your claude_desktop_config.json file (typically in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows) and add the following:

{
  "mcpServers": {
    "ebay_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Restart Claude Desktop. The application will execute the npx command, establish the SSE connection, and request the tools/list endpoint to load the eBay tools.

eBay Hero Tools

Truto automatically generates well-documented tools from the eBay API schemas. When Claude calls tools/list, it receives a flat list of these tools, complete with JSON Schemas detailing exactly which query and body parameters are required.

Here are the highest-leverage tools available for automating eBay e-commerce workflows.

list_all_e_bay_orders

This tool retrieves one or more orders based on their creation date, modification date, or fulfillment status. Truto automatically handles eBay's next link pagination across pages.

Usage Notes: Use this tool to monitor a seller's queue or locate a specific buyer's purchase history. It accepts filters like creationdate and orderfulfillmentstatus.

"Find all unfulfilled eBay orders created in the last 48 hours and summarize the items that need to be picked and packed."

get_single_e_bay_order_by_id

Retrieves the complete contents of an order based on its unique orderId.

Usage Notes: The orderId is a required path parameter. This tool is critical for fetching detailed shipping addresses, line item SKUs, and exact payment breakdowns before initiating refunds or fulfillment workflows.

"Look up the details for eBay order ID 12-34567-89012. Tell me the shipping address and the total amount paid."

e_bay_orders_refund

Initiates a refund for an order. Truto manages the complex EU/UK digital signature requirements behind the scenes if applicable.

Usage Notes: Requires the order_id. You must provide the refund reason, the amount, and optionally the line items being refunded in the JSON payload.

"The buyer for order 12-34567-89012 received a damaged item. Issue a full refund for the order with the reason 'ITEM_DAMAGED'."

list_all_e_bay_conversations

Retrieves one or more message conversations associated with the seller's account.

Usage Notes: Requires the conversation_type query parameter (e.g., messages from members vs. eBay system messages). The app keyset must have the commerce.message OAuth scope.

"Check my recent eBay buyer messages. Are there any unresolved threads where a buyer is asking about a delayed shipment?"

create_a_e_bay_message

Starts a conversation with another user or sends a message in an existing conversation.

Usage Notes: Either the conversationId (to reply) or otherPartyUsername (to initiate) is required.

"Send a reply to the conversation ID 987654321 letting the buyer know that their refund has been processed and should appear on their statement in 3-5 business days."

e_bay_inventory_items_bulk_upsert

Creates or updates up to 25 new inventory item records in a single call.

Usage Notes: Requires the content_language header value. You must pass an array of items, each with a SKU, product details, and availability data. Ideal for syncing stock levels from a master warehouse database.

"Update the eBay inventory levels for SKUs 'TSHIRT-BLK-M' to 15 units and 'TSHIRT-WHT-L' to 0 units using the bulk upsert tool."

list_all_e_bay_payment_disputes

Retrieves open or recently closed payment disputes (chargebacks or eBay buyer protection claims) filed against the seller.

Usage Notes: Essential for financial reconciliation and automated customer support triage. Can be filtered by dispute state.

"Fetch all open eBay payment disputes. Summarize the dispute reasons and the amount contested for each open case."

For a complete list of all available eBay tools, including detailed parameter requirements and JSON schemas, visit the eBay integration page.

Workflows in Action

By chaining these tools together, Claude can execute multi-step operations that traditionally required human intervention. Here are two real-world workflows.

Workflow 1: Automated Order Refund & Buyer Notification

When a customer support agent asks Claude to process a return due to damage, Claude must retrieve the order, calculate the refund, execute it, and inform the buyer.

"Process a full refund for order 17-09876-54321 because the item arrived damaged. Once the refund is issued, send a message to the buyer apologizing for the inconvenience."

sequenceDiagram
    participant User
    participant Claude as Claude (LLM)
    participant MCP as Truto MCP Server
    participant Upstream as "Upstream API (eBay)"

    User->>Claude: "Process refund for 17-09876-54321..."
    Claude->>MCP: Call get_single_e_bay_order_by_id(id: "17-09876-54321")
    MCP->>Upstream: GET /sell/fulfillment/v1/order/17-09876-54321
    Upstream-->>MCP: Return order details & buyer username
    MCP-->>Claude: JSON order data
    Claude->>MCP: Call e_bay_orders_refund(order_id, reason, amount)
    MCP->>Upstream: POST /sell/fulfillment/v1/order/17-09876-54321/issue_refund
    Note over MCP,Upstream: Truto handles EU/UK HTTP Digital Signatures if required
    Upstream-->>MCP: 201 Created (Refund successful)
    MCP-->>Claude: Success confirmation
    Claude->>MCP: Call create_a_e_bay_message(otherPartyUsername, text)
    MCP->>Upstream: POST /commerce/message/v1/message
    Upstream-->>MCP: 201 Created (Message sent)
    MCP-->>Claude: Success confirmation
    Claude-->>User: "Refund processed successfully and buyer notified."

Step-by-step breakdown:

1. Claude calls get_single_e_bay_order_by_id to fetch the total order amount and the buyer's username.
2. Claude calls e_bay_orders_refund using the extracted amount and the 'damaged' reason.
3. Claude calls create_a_e_bay_message targeting the buyer's username, generating a polite apology and confirmation of the refund.
4. The user receives a summary confirming the workflow is complete.

Workflow 2: Customer Support & Dispute Triage

Support teams waste hours cross-referencing buyer complaints against official payment disputes. Claude can automate this investigation.

"Check my recent buyer messages. If anyone is complaining about a missing package, check if they have also filed a payment dispute. Summarize the findings."

flowchart TD
    A["User Prompt:<br>Check messages for missing packages and cross-reference disputes"] --> B["list_all_e_bay_conversations"]
    B --> C{"Did LLM find<br>missing package keywords?"}
    C -->|Yes| D["Extract Buyer Username/Order ID"]
    C -->|No| E["Stop Workflow"]
    D --> F["list_all_e_bay_payment_disputes"]
    F --> G["Match Order ID to Dispute ID"]
    G --> H["Return Summary to User"]

Step-by-step breakdown:

1. Claude calls list_all_e_bay_conversations and reads the recent message bodies.
2. The LLM's natural language processing identifies any threads containing complaints about missing items.
3. Claude extracts the buyer and order context, then calls list_all_e_bay_payment_disputes.
4. Claude cross-references the order IDs. If a match is found, it alerts the user that the complaining buyer has already initiated a chargeback, preventing the support team from accidentally issuing a double-refund.

Security and Access Control

When providing AI agents with write access to a live eBay account, enforcing least-privilege security is critical. Truto's MCP servers provide several layers of access control out of the box:

• Method Filtering: By defining "methods": ["read"] during server creation, you can strictly prevent the LLM from executing any POST, PUT, PATCH, or DELETE operations, ensuring the agent is read-only.
• Tag Filtering: Integrations group tools logically (e.g., inventory, orders, finances). You can limit the MCP server to specific tags, preventing a customer support agent from accidentally accessing the finances API.
• Extra Authentication (require_api_token_auth): By setting this to true, possessing the MCP URL is not enough. The connecting client must also supply a valid Truto API token in the Authorization header, preventing unauthorized internal access if the URL is leaked in logs.
• Server Expiration (expires_at): You can set a strict TTL for the server. Truto uses edge KV storage and distributed alarm workers to automatically delete the token and its associated metadata exactly when it expires, leaving no stale credentials.

Wrap Up

Building an MCP server for eBay requires deep knowledge of e-commerce data structures, regulatory signature requirements, and legacy API idiosyncrasies. By using a managed platform, engineering teams can skip the integration boilerplate and focus purely on designing high-leverage agent workflows.

Whether you are automating refund processing, syncing bulk inventory, or triaging buyer messages, Truto provides a production-grade translation layer between Claude and your SaaS ecosystems.