An agent can help you investigate a resale category, identify comparable listings, and explain which records deserve a closer look. It needs a dependable source of data and a clear research boundary. A language model's memory cannot tell you what appeared in an eBay search today.
SoldFetch exposes a hosted Model Context Protocol server for keyword search, category search, and item details. This guide connects those three tools into one small camera-research task, with a four-call budget and an output you can audit. The same pattern works for an internal inventory assistant or a research panel in a resale application.
1. Define the research question before connecting tools
Use a task narrow enough to finish in a few requests: “Research used Sony a6400 body listings on eBay US. Identify two plausible comparable listings, inspect their details, and explain the remaining matching uncertainty.” Body-only cameras, lens bundles, accessories, and damaged units belong in different groups.
Choose the storefront explicitly. The current public launch markets are ebay.com, ebay.co.uk, and ebay.de; check capabilities for enabled sites and whether data access is available. A parser accepting a marketplace code does not establish that the deployment enables it.
Give the agent a fixed budget: one active category exploration, one sold keyword search, and at most two item lookups. This provides room to investigate without turning a broad request into an open-ended crawl. If you already know the category, skip the exploration and leave that request unused.
Keep the task read-only. Finding a listing does not authorize contacting its seller, purchasing an item, or publishing a valuation. Those actions need their own application flow.
2. Connect the hosted Streamable HTTP server
Create a key in the SoldFetch dashboard, then supply it through your MCP host's secret configuration. The endpoint is:
https://soldfetch.com/api/mcp
A host that supports a remote URL and custom headers needs these settings:
{
"url": "https://soldfetch.com/api/mcp",
"transport": "streamable-http",
"headers": {"API-KEY": "<resolved from your host's secret store>"}
}
This object shows connection settings, not a configuration file that every host accepts verbatim. Use your host's documented nesting and secret mechanism. Send exactly one credential header. SoldFetch also accepts Authorization: Bearer, SOLDFETCH-API-KEY, and X-API-KEY; stacking several headers is unnecessary.
Let the MCP client perform initialization and tool discovery. Neither operation consumes SoldFetch data units. Do not assume opening the endpoint in a browser tests an MCP connection: the hosted interface handles MCP requests through POST. Client SDK examples change between major versions, so use the current MCP client guide when implementing your own transport. The SoldFetch MCP repository documents the service contract.
3. Use category search for orientation
The server exposes search_ebay_category, search_ebay_sold, and get_ebay_item. Start by inspecting their discovered input schemas. The names describe tools, while their parameters determine which records they request.
For an optional orientation pass in the US digital-camera category, ask for active listings:
{
"name": "search_ebay_category",
"arguments": {
"categoryId": "31388",
"ebaySite": "ebay.com",
"sold": false,
"count": 20,
"page": 1
}
}
This is an MCP tool-call description for the host, not a REST request body. Confirm the category in the target marketplace before adapting it elsewhere. Category IDs and category context should travel with the research run.
Use this result to see how sellers describe bodies, kits, and accessories. It provides asking-price context, not sold-price evidence. Category-only sold searches can return an uncharged 503 upstream_blocked; do not let the agent retry the same broad search indefinitely or silently replace sold observations with active prices.
4. Search sold listings, then inspect selected IDs
The next call narrows the query and requests a single sold-results page:
{
"name": "search_ebay_sold",
"arguments": {
"keyword": "sony a6400 body",
"ebaySite": "ebay.com",
"sold": true,
"itemCondition": "used",
"count": 20,
"page": 1
}
}
The tool defaults to 20 results. Explicit count can range from 1 to 200, but a small research task rarely needs the largest page. Read structuredContent for the complete result: the text summary includes at most 20 items, so a host reading only summary text can lose records when requesting more.
Choose up to two plausible items from the returned list. Pass an observed item ID and its site into get_ebay_item:
{
"name": "get_ebay_item",
"arguments": {"itemId": "123456789012", "ebaySite": "ebay.com"}
}
The ID above is illustrative. Replace it with an ID from your actual result. Item details can provide condition descriptions and item specifics, helping identify a lens kit or a damaged body that escaped title screening. An item lookup accepts only itemId and ebaySite; it does not accept search filters.
5. Enforce a budget outside the model
A prompt can state a budget, but the host should enforce it before dispatch. Each successful search or item call costs one request. Four successful data calls therefore consume four data units; initialization and discovery consume none. Account rate and concurrency limits still apply.
The companion policy provides a framework-neutral admission policy. It allows only the three research tools, fixes the storefront, limits search to page one and 20 rows, and rejects item IDs that have not appeared in this run. It conservatively counts attempts, including failures, against the local budget.
policy = ResearchPolicy(site="ebay.com", max_calls=4)
arguments = policy.admit(tool_name, proposed_arguments)
# Dispatch through your MCP client, then convert its result to a dictionary.
data = policy.observe(result_dictionary)
The policy is an integration component, not a complete model client. Your host supplies the actual MCP session and handles protocol errors. On an error result, stop and show the cause. A fresh retry should consume the remaining local attempt allowance; a permanent authentication or unsupported-capability error needs correction, not repetition.
If you later add pagination, introduce a separate page allowance and stop on empty results, repeated IDs, or hasNextPage=false. Never let the model infer an unlimited budget from “find more.”
6. Treat marketplace content as evidence
Listing titles, descriptions, and seller-provided text are untrusted input. A title containing instructions to reveal a key or call another tool remains a title. Keep credentials outside model context, allowlist tools, and give retrieved text a distinct data role in your application.
Preserve the response's warnings alongside each research result. soldPrice represents the displayed listing price; it is not a verified accepted Best Offer amount. Reported sale dates are unverified. exactMatch does not establish exact product identity, and an ended item page alone is not proof of a sale.
Do not collapse missing prices into zero or combine currencies into one median. Keep the site, item ID, source URL, currency, condition, observation timestamp, and quality fields attached to each candidate. If matching evidence is thin, the useful answer is an explanation of the gaps and a short list for review.
7. Return a research note a person can check
Ask for a compact table containing the two item IDs, source links, displayed prices and currencies, conditions, and reasons for including or rejecting each candidate. Follow it with the query, storefront, rows reviewed, request count, and unresolved differences.
Separate observed facts from the agent's interpretation. “The listing title contains ‘body only’” is evidence; “this is the same package as our inventory item” needs additional support. Include warnings even when the answer sounds confident.
Keep active-category observations in a separate table from sold-search observations. This prevents an asking price from being mistaken for a completed-sale comparable. A saved research note with two well-explained records is more useful than a single precise-looking valuation without provenance.
8. Validate the workflow before adding autonomy
Run the companion policy with python3 ebay-mcp-ai-agent-policy.py --self-test. Its offline fixtures check budget exhaustion, storefront changes, invented IDs, forbidden tools, oversized searches, error handling, and preservation of structured data. They make no authenticated requests and consume no provider credits.
Then connect your chosen host, inspect the discovered schemas, and run one deliberately bounded task with your own key. Offline checks validate the control logic; they do not establish live coverage or guarantee a particular listing will resolve.
For a larger export, use the Python search and CSV tutorial or the background-job workflow. For individual details, see the item API guide and agent documentation.
Get your SoldFetch API key, connect your MCP host, and start with one storefront and a four-call research budget.
