eBay MCP — Remote Edition

<div align="center">

A Model Context Protocol (MCP) server providing AI assistants with comprehensive access to eBay's Sell APIs. 325+ tools covering inventory management, order fulfillment, marketing campaigns, analytics, developer tools, and more.

API Coverage: 100% of eBay Sell APIs (270+ unique endpoints)

</div>

---

Overview

This project extends Yosef Hayim's eBay MCP with hosted, multi-user deployment while preserving local STDIO mode. Key additions:

• Hosted Streamable HTTP — deploy anywhere, serve multiple users from one instance
• MCP OAuth 2.1 — browser-based eBay login with automatic token management; OAuth-aware clients (Cline) connect without manual token pasting
• Environment-scoped routes — /sandbox/mcp and /production/mcp hard-bind their eBay environment
• Cloudflare KV / Upstash Redis — persistent multi-user token and session storage with TTL-aligned expiry
• Admin session management — inspect, revoke, or delete sessions via authenticated endpoints
• eBay Research session persistence — Playwright storage state to KV/Redis/filesystem via EBAY_RESEARCH_SESSION_STORE
• QStash-triggered Telegram alerts — expiry callbacks notify operators before research auth degrades

---

⚠️ Disclaimer

This is an open-source project provided "as is" without warranty of any kind. Not affiliated with, endorsed by, or sponsored by eBay Inc. Test thoroughly in sandbox before production.

---

Table of Contents

• Choose a runtime mode
• Prerequisites
• Local mode setup
• Hosted mode setup
• Tool discovery for agents
• Available tools
• Development
• Testing & validation
• Troubleshooting
• Resources

---

Choose a runtime mode

Mode	Command	Transport	Best for	Authorization model
Local STDIO	pnpm start / pnpm run dev	stdin/stdout	Single-user local AI client (Claude Desktop, Cline, Cursor, etc.)	The local process reads eBay credentials and optional EBAY_USER_REFRESH_TOKEN from environment variables.
Hosted HTTP	pnpm run start:http / pnpm run dev:http	Streamable HTTP	Multi-user server deployment; remote MCP clients	Users authorize through browser OAuth. Requests can use normal session Bearer auth or opt into server-request auth with X-Ebay-Server-Request: true.

Both modes use the same eBay tool registry. Local STDIO is best when one trusted local client owns the eBay credentials. Hosted HTTP runs an Express server with OAuth 2.1 discovery, environment-scoped route trees, server-side token/session storage, and admin-only operational endpoints.

---

Prerequisites

All modes:

• Node.js ≥ 18.0.0
• pnpm (or npm — npm install -g pnpm)
• An eBay Developer Account

Getting credentials:

1. Log in to eBay Developer Portal
2. Create an application, copy App ID (Client ID) and Cert ID (Client Secret)
3. Under User Tokens → Add RuName, register your public HTTPS OAuth callback URL and copy the generated RuName string

EBAY_RUNAME and the public Redirect URL are distinct. EBAY_RUNAME is the eBay-generated RuName string used as eBay's OAuth redirect_uri identifier (for example, YourApp-YourApp-SB-abcdefghi). The public Redirect URL is the real browser callback URL you register in eBay, such as https://your-server.com/oauth/callback or https://ebay-local.test:3000/oauth/callback; it is derived from PUBLIC_BASE_URL in this project. Do not use either value as a fallback for the other.

HTTPS callback URL (required by eBay)

eBay requires HTTPS for OAuth callbacks. For local dev, use mkcert:

brew install mkcert nss
mkcert -install
mkcert ebay-local.test
echo "127.0.0.1  ebay-local.test" | sudo tee -a /etc/hosts

Register https://ebay-local.test:3000/oauth/callback in the Developer Portal. Add to .env:

PUBLIC_BASE_URL=https://ebay-local.test:3000
EBAY_LOCAL_TLS_CERT_PATH=/path/to/ebay-local.test.pem
EBAY_LOCAL_TLS_KEY_PATH=/path/to/ebay-local.test-key.pem

Trust mkcert CA in Node.js

VS Code's extension host uses Node.js, which doesn't read macOS system keychain by default. Trust the cert:

# Current session (Dock/Spotlight-launched apps):
launchctl setenv NODE_EXTRA_CA_CERTS "$(mkcert -CAROOT)/rootCA.pem"

# Persist across reboots:
cat > ~/Library/LaunchAgents/com.local.mkcert-node-trust.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.local.mkcert-node-trust</string>
  <key>ProgramArguments</key>
  <array>
    <string>launchctl</string><string>setenv</string>
    <string>NODE_EXTRA_CA_CERTS</string>
    <string>/Users/YOUR_USERNAME/Library/Application Support/mkcert/rootCA.pem</string>
  </array>
  <key>RunAtLoad</key><true/>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.local.mkcert-node-trust.plist

# Terminal-launched apps — add to ~/.zshrc:
echo 'export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"' >> ~/.zshrc

Then fully quit and reopen VS Code.

For hosted deployments, register your server's public HTTPS URL instead.

---

Local mode setup

Install

# Option A — global install (no build step):
pnpm install -g ebay-mcp-remote-edition

# Option B — clone and build (contributors):
git clone https://github.com/mrnajiboy/ebay-mcp-remote-edition.git
cd ebay-mcp-remote-edition
pnpm install && pnpm run build

Configure credentials

Create .env (see .env.example):

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_RUNAME=your_runame_string       # eBay-generated RuName, not a URL
EBAY_REDIRECT_URI=                  # legacy env name; do not set to the public callback URL
EBAY_ENVIRONMENT=sandbox           # or production
EBAY_MARKETPLACE_ID=EBAY_US        # optional, defaults to EBAY_US
EBAY_CONTENT_LANGUAGE=en-US        # optional, defaults to en-US
EBAY_USER_REFRESH_TOKEN=           # populated by setup wizard

Authentication tiers:

Method	Rate limit	How
Client credentials (default)	1,000 req/day	Set EBAY_CLIENT_ID + EBAY_CLIENT_SECRET
User tokens (recommended)	10,000–50,000 req/day	Run pnpm run setup to complete OAuth

Run the setup wizard

pnpm run setup          # interactive: env selection, credentials, OAuth, client config
pnpm run setup --quick  # skip optional steps
pnpm run setup --diagnose  # connectivity and token checks only

Local client configuration

{
  "mcpServers": {
    "ebay": {
      "command": "npx",
      "args": ["-y", "ebay-mcp-remote-edition"],
      "env": {
        "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
        "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_RUNAME": "YOUR_RUNAME",
        "EBAY_REDIRECT_URI": "",
        "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

Config file locations:

Client	Config file
Cline	~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor	~/.cursor/mcp.json or .cursor/mcp.json

Zed, Windsurf, Continue.dev, Roo Code, and Amazon Q follow the same mcpServers JSON shape.

---

Hosted mode setup

Environment variables

Hosted HTTP reads the same eBay credential variables as local STDIO plus the HTTP, storage, and security variables below. The start script is pnpm run start:http; development uses pnpm run dev:http.

# Required for hosted OAuth URLs and eBay callback registration
PUBLIC_BASE_URL=https://your-server.com

# Required eBay credentials unless EBAY_CONFIG_FILE provides them
EBAY_CLIENT_ID=
EBAY_CLIENT_SECRET=
EBAY_RUNAME=
EBAY_REDIRECT_URI=                  # legacy env name; not the public callback URL
# Recommended when serving both environments from one host
EBAY_PRODUCTION_CLIENT_ID=
EBAY_PRODUCTION_CLIENT_SECRET=
EBAY_PRODUCTION_RUNAME=
EBAY_PRODUCTION_REDIRECT_URI=
EBAY_SANDBOX_CLIENT_ID=
EBAY_SANDBOX_CLIENT_SECRET=
EBAY_SANDBOX_RUNAME=
EBAY_SANDBOX_REDIRECT_URI=

# Required for hosted multi-user token/session persistence
EBAY_TOKEN_STORE_BACKEND=upstash-redis  # cloudflare-kv | upstash-redis | memory
UPSTASH_REDIS_REST_URL=                 # required when backend is upstash-redis
UPSTASH_REDIS_REST_TOKEN=               # required when backend is upstash-redis
CLOUDFLARE_ACCOUNT_ID=                  # required when backend is cloudflare-kv
CLOUDFLARE_KV_NAMESPACE_ID=             # required when backend is cloudflare-kv
CLOUDFLARE_API_TOKEN=                   # required when backend is cloudflare-kv

# Required for admin/validation endpoints and privileged MCP bypass
ADMIN_API_KEY=

# Optional HTTP/server behavior
PORT=3000                               # defaults to 3000; many hosts inject this
MCP_HOST=0.0.0.0                        # defaults to 0.0.0.0
EBAY_ENVIRONMENT=production             # root/legacy default selector
EBAY_DEFAULT_ENVIRONMENT=production     # fallback when EBAY_ENVIRONMENT is unset
SESSION_TTL_SECONDS=2592000             # default: 30 days
OAUTH_START_KEY=                        # optional gate for /oauth/start
EBAY_CONFIG_FILE=/etc/secrets/ebay-config.json
EBAY_MARKETPLACE_ID=EBAY_US
EBAY_CONTENT_LANGUAGE=en-US
EBAY_LOG_LEVEL=info

# Optional validation runner identity
VALIDATION_RUNNER_USER_ID=
VALIDATION_RUNNER_USER_ID_SANDBOX=
VALIDATION_RUNNER_USER_ID_PRODUCTION=

# Optional validation/research providers and alerts
RAPIDGATE_API_URL=
RAPIDGATE_API_KEY=
PERPLEXITY_API_KEY=
TWITTER_BEARER_TOKEN=
YOUTUBE_API_KEY=
REDDIT_CLIENT_ID=
REDDIT_CLIENT_SECRET=
REDDIT_USER_AGENT=
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
QSTASH_URL=
QSTASH_TOKEN=
QSTASH_CURRENT_SIGNING_KEY=
QSTASH_NEXT_SIGNING_KEY=
EBAY_RESEARCH_SESSION_ALERTS_ENABLED=true
EBAY_RESEARCH_SESSION_ALERT_CALLBACK_URL=

# eBay Research/Terapeak first-party session source.
# Set this explicitly in hosted deployments. If unset, research sessions default
# to Cloudflare KV even when EBAY_TOKEN_STORE_BACKEND=upstash-redis.
EBAY_RESEARCH_SESSION_STORE=upstash-redis # cloudflare_kv | upstash-redis | filesystem | none
EBAY_RESEARCH_SESSION_ALLOW_FILESYSTEM_FALLBACK=false

EBAY_TOKEN_STORE_BACKEND defaults to Cloudflare KV when unset or unrecognized. Use memory only for tests or throwaway local development because hosted sessions and tokens are lost on restart. EBAY_RESEARCH_SESSION_STORE is separate from OAuth token storage. Set it to upstash-redis when Terapeak/eBay Research cookies are stored in Upstash.

Secret file

Mount a JSON file with credentials (e.g., Render Secret File at /etc/secrets/ebay-config.json):

{
  "production": {
    "clientId": "PROD_CLIENT_ID",
    "clientSecret": "PROD_CLIENT_SECRET",
    "redirectUri": "YOUR_PRODUCTION_RUNAME",
    "ruName": "YOUR_PRODUCTION_RUNAME"
  },
  "sandbox": {
    "clientId": "SANDBOX_CLIENT_ID",
    "clientSecret": "SANDBOX_CLIENT_SECRET",
    "redirectUri": "YOUR_SANDBOX_RUNAME",
    "ruName": "YOUR_SANDBOX_RUNAME"
  }
}

Deploy to Render / Railway / Coolify

1. Connect your repo as a Web Service
2. Build: pnpm install && pnpm run build
3. Start: pnpm run start:http
4. Add environment variables + secret file

For Nixpacks-based platforms (Railway, Coolify): nixpacks.toml handles pnpm, build, Chromium install, and start automatically.

OAuth flows

GET /sandbox/oauth/start      # sandbox browser login
GET /production/oauth/start   # production browser login

If OAUTH_START_KEY is set, start URLs require either ?key=YOUR_KEY or the X-OAuth-Start-Key: YOUR_KEY header. The server also includes this key as key in generated authorization_url values for unauthenticated MCP requests.

After login, the callback page shows three hosted auth options with copy buttons:

Hosted auth mode	How to select it	Best for
User/session mode	Send Authorization: Bearer <session-token> and omit X-Ebay-Server-Request	Normal OAuth-aware MCP clients and user-scoped desktop clients.
Server request mode — identity headers	Send X-Ebay-Server-Request: true, X-Ebay-Client-Id, X-Ebay-User-Id, and optional X-Ebay-Environment	Server/client setups that need to handle both regular user requests and backend server requests without copying a session token.
Server request mode — bearer-capable clients	Send X-Ebay-Server-Request: true plus Authorization: Bearer <mcp-server-issued-bearer-token>	MCP clients or automation platforms that can store an authorization header but should not use the admin key.

Switching between modes is per request, not a server-wide environment toggle. The same hosted MCP server can handle user/session requests and server requests concurrently; the client chooses server mode by adding X-Ebay-Server-Request: true.

Session TTL schedule:

Record	TTL
OAuth state	15 minutes
MCP auth code	10 minutes
Session	30 days (configurable)
User token	eBay refresh token expiry (fallback: 18 months)

MCP endpoints

Environment-scoped (recommended):

POST/GET/DELETE /sandbox/mcp
POST/GET/DELETE /production/mcp

Each includes OAuth 2.1 discovery: GET /sandbox/.well-known/oauth-authorization-server

Legacy auto-detect:

POST/GET/DELETE /mcp   # resolves from ?env= or EBAY_ENVIRONMENT/EBAY_DEFAULT_ENVIRONMENT

Auth behavior:

• GET /mcp without token → redirects to oauth/start
• POST /mcp without token → 401 JSON with authorization_url, resource_metadata, and a WWW-Authenticate Bearer challenge
• Normal user requests: Authorization: Bearer <session-token>
• Server requests with identity headers: X-Ebay-Server-Request: true, X-Ebay-Client-Id: <client-id>, X-Ebay-User-Id: <user-id>, X-Ebay-Environment: sandbox|production
• Server requests with bearer-capable clients: X-Ebay-Server-Request: true plus Authorization: Bearer <mcp-server-issued-bearer-token>
• Privileged admin bypass: Authorization: Bearer <ADMIN_API_KEY> when ADMIN_API_KEY is configured

The X-Ebay-Server-Request header is intentionally client-side and per-request. Leave it off for normal user/session OAuth calls. Add it when the MCP client is making a server-style request and should resolve the stored Redis/KV user token record by headers or by the MCP server-issued bearer lookup token. This bearer lookup token is generated by this MCP server on the OAuth callback page; it is not an eBay user access token, eBay refresh token, eBay client-credentials/app token, legacy hosted session token, or ADMIN_API_KEY.

Admin key bypass

ADMIN_API_KEY is used in two distinct ways:

Use	Exact implementation	Scope
Admin/validation HTTP routes	X-Admin-API-Key: <ADMIN_API_KEY> header	Required for /admin/session/:sessionToken, /admin/session/:sessionToken/revoke, /admin/session/:sessionToken, /sandbox/validation/*, /production/validation/*, and legacy /validation/*.
MCP authorization bypass	Authorization: Bearer <ADMIN_API_KEY> header	Lets privileged server-to-server/admin tooling call /sandbox/mcp, /production/mcp, or /mcp without a hosted user session lookup. The request runs with userId set to admin and the requested environment.

The admin bypass does not use query parameters or request body fields. ADMIN_API_KEY must be configured on the server; if it is unset, admin HTTP routes return 500 and the MCP bypass is disabled.

Security caveats:

• Treat ADMIN_API_KEY as a privileged root credential for this MCP server.
• Generate a long, random value and store it only in your deployment secret manager.
• Use it only for server-to-server automation, operational checks, or admin tooling. Do not ship it to browsers, desktop clients, or regular users.
• OAuth browser authorization and hosted session tokens remain the normal path for user MCP access.

Utility endpoints:

GET  /health                               # health check (no auth)
GET  /whoami                               # session identity (Bearer token)
GET  /admin/session/:sessionToken          # view session (admin key)
POST /admin/session/:sessionToken/revoke   # revoke session
DELETE /admin/session/:sessionToken        # delete session

Admin endpoints

All /admin/* routes accept authentication via either:

• Header: X-Admin-API-Key: <ADMIN_API_KEY>
• Query param: ?key=<ADMIN_API_KEY> (useful for browser access)

GET  /admin/token-status                    # OAuth + Playwright session health
POST /admin/oauth/start-for-validation       # Start OAuth flow for validation runner
POST /admin/playwright-session              # Store Playwright storage state JSON
GET  /admin/playwright-capture              # Browser UI to capture eBay Research cookies
GET  /admin/research-session/live           # noVNC live browser rescue page
GET  /admin/research-session/live?format=json # live browser rescue status JSON
POST /admin/research-session/live/open      # start headed server Chrome for eBay Research
POST /admin/research-session/live/persist   # persist live browser state into research storage

/admin/research-session/live is the preferred rescue lane when eBay Research/Terapeak is blocked by login, captcha, 2FA, or "Pardon Our Interruption". Open the admin page with a browser-safe admin key query parameter, click Open Live Session, connect to noVNC with the displayed VNC password, complete any eBay challenge in the server Chrome window, and make sure the final browser page is https://www.ebay.com/sh/research before clicking Persist Live Session.

A successful persist response should show ok: true, cookieCount > 0, and validation success against the eBay Research ACTIVE endpoint with real research modules such as ResearchAggregateModule and ActiveSearchResultsModule. In hosted Upstash deployments the persisted storage state is written to ebay_research_storage_state_json with metadata in ebay_research_storage_state_meta; future validation runs consume that stored state automatically. Persisting only locks in the Terapeak session — Airtable rows are updated after validation rows are rerun.

If the backend validation debug reports providerResolution.activeSource = ebay_research_ui and providerResolution.soldSource = ebay_research_ui with soldFallbackUsed = false, the run is using authenticated first-party eBay Research/Terapeak data rather than the temporary sold-data fallback. The write-resolution debug should mark active fields as research_active, sold aggregate fields as research_sold, and day-level sold velocity as research_sold_rows when row-level sold dates are available.

/admin/playwright-capture renders a self-service page for renewing the eBay Research Playwright session. Open it in a browser with the admin key as a query parameter:

https://your-server.com/admin/playwright-capture?key=YOUR_ADMIN_API_KEY

The page has two tabs:

1. Auto-Capture — loads eBay Research in an iframe (may be blocked by eBay's security policies)
2. Manual Export — provides step-by-step instructions to export cookies from Chrome DevTools, a bookmarklet for one-click cookie copying, and a text area to paste and submit the JSON

Submitted cookies are validated against the authenticated eBay Research ACTIVE endpoint before persistence, stored in the configured session backend (Upstash Redis / Cloudflare KV / filesystem), and written with a long KV TTL. Cookie expiry is tracked in metadata so the runtime can report missing/expired Terapeak auth separately from provider parsing failures.

Validation endpoints

POST /sandbox/validation/run          # run validation pipeline
POST /production/validation/run

GET  /sandbox/validation/health       # check runner status
GET  /production/validation/health

Both require X-Admin-API-Key: <ADMIN_API_KEY>. The server impersonates the configured validation runner user from VALIDATION_RUNNER_USER_ID env vars.

See Validation architecture below for provider details.

Remote client configuration

Cline (automatic OAuth):

{
  "mcpServers": {
    "ebay-sandbox": { "url": "https://your-server.com/sandbox/mcp" },
    "ebay-production": { "url": "https://your-server.com/production/mcp" }
  }
}

Cline auto-discovers OAuth, opens browser login, exchanges auth code, and stores session token.

Claude Desktop / Cursor (Bearer token):

1. Open https://your-server.com/sandbox/oauth/start → complete eBay login → copy session token
2. Configure client:

{
  "mcpServers": {
    "ebay-sandbox": {
      "url": "https://your-server.com/sandbox/mcp",
      "headers": { "Authorization": "Bearer YOUR_SESSION_TOKEN" }
    }
  }
}

Server request mode (custom headers):

1. Open https://your-server.com/sandbox/oauth/start or https://your-server.com/production/oauth/start
2. Complete eBay login
3. Copy the server request headers shown on the callback page
4. Configure the MCP client with those headers:

{
  "mcpServers": {
    "ebay-production-server": {
      "url": "https://your-server.com/production/mcp",
      "headers": {
        "X-Ebay-Server-Request": "true",
        "X-Ebay-Client-Id": "YOUR_EBAY_CLIENT_ID",
        "X-Ebay-User-Id": "STORED_USER_ID_FROM_CALLBACK",
        "X-Ebay-Environment": "production"
      }
    }
  }
}

Server request mode (bearer-capable clients): Use this when the MCP client can set Authorization but cannot easily send several custom identity headers:

{
  "mcpServers": {
    "ebay-production-server": {
      "url": "https://your-server.com/production/mcp",
      "headers": {
        "X-Ebay-Server-Request": "true",
        "Authorization": "Bearer MCP_SERVER_ISSUED_BEARER_TOKEN_FROM_CALLBACK"
      }
    }
  }
}

Make / Zapier / other platforms:

1. Complete OAuth via browser at /oauth/start
2. If the platform supports multiple headers, use server request mode identity headers
3. If the platform only supports one auth header, use server request mode with the MCP server-issued bearer lookup token from the callback page
4. Set MCP URL to https://your-server.com/sandbox/mcp

---

Tool discovery for agents

AI agents discover tools through the MCP protocol's tools/list call. The eBay MCP server exposes 325+ tools with a predictable naming and description structure optimized for agent searchability.

Tool naming convention

All tools follow the pattern ebay_<action>_<resource>:

Action	Meaning	Examples
get	Read/fetch	ebay_get_inventory_item, ebay_get_offers
create	Create new	ebay_create_offer, ebay_create_fulfillment_policy
update	Modify existing	ebay_update_offer, ebay_update_inventory_item
delete	Remove	ebay_delete_offer, ebay_delete_inventory_item
publish	Activate	ebay_publish_offer
withdraw	Deactivate	ebay_withdraw_offer
revise	Modify listing	ebay_revise_listing
bulk_	Batch operations	ebay_bulk_create_offer, ebay_bulk_update_price_quantity

Tool descriptions are self-documenting

Each tool description includes:

• What it does — concise action description
• OAuth scope required — the minimum scope needed
• Minimum scope URL — for fine-grained permission setup

Example:

Get a specific inventory item by SKU.

Required OAuth Scope: sell.inventory.readonly or sell.inventory
Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

Tools organized by category

Tools are grouped into 13 category files in src/tools/definitions/:

Category file	Tool prefix	Key operations
inventory.ts	ebay_*inventory*, ebay_*offer*	CRUD inventory items, offers, locations, bulk ops
fulfillment.ts	ebay_*fulfillment*, ebay_*shipment*	Shipments, fulfillment orders, shipping labels
account.ts	ebay_*policy*	Payment, return, fulfillment policies
marketing.ts	ebay_*promotion*, ebay_*markdown*	Promotions, markdown listings
analytics.ts	ebay_*analytics*, ebay_*report*	Analytics, reporting
communication.ts	ebay_*message*, ebay_*feedback*	Messages, feedback, notifications
metadata.ts	ebay_*metadata*, ebay_*policies*	Category policies, listing metadata
taxonomy.ts	ebay_*category*	Category tree, suggestions, item specifics
browse.ts	ebay_*browse*, ebay_*product*	Browse/search products
trading.ts	ebay_*listing*, ebay_*create_listing*	Trading API (XML/SOAP) operations
developer.ts	ebay_*signing*, ebay_*vero*	Key management, VERO reports
other.ts	Mixed	Misc/legacy endpoints
token-management.ts	ebay_*oauth*, ebay_*token*	OAuth helpers, token management

How agents find the right tool

1. Search by name pattern — ebay_get_* for reads, ebay_create_* for writes, ebay_*offer* for offers
2. Search by description — descriptions contain action keywords and resource names
3. Search by OAuth scope — sell.inventory for inventory, sell.fulfillment for shipping
4. Use tools/list — agents receive the full tool list with names and descriptions; filter programmatically

Tool annotations

Tools carry MCP annotations that help agents understand behavior:

Annotation	Meaning
readOnlyHint: true	Safe to call; no side effects
destructiveHint: true	Irreversible; use caution
idempotentHint: true	Safe to retry
openWorldHint: true	May interact with external services

---

Available tools

325+ tools across all eBay Sell API categories. Full source: src/tools/definitions/

---

Development

Commands

Command	Description
pnpm run build	Compile TypeScript
pnpm start	Run local STDIO server
pnpm run start:http	Run hosted HTTP server
pnpm run dev	STDIO with hot reload
pnpm run dev:http	HTTP with hot reload
pnpm test	Run tests
pnpm run setup	Interactive setup wizard
pnpm run sync	Download eBay OpenAPI specs, regenerate types
pnpm run diagnose	Check config and connectivity
pnpm run typecheck	TypeScript type checking
pnpm run check	Typecheck + lint + format
pnpm run fix	Auto-fix lint and format

pnpm run sync

Download latest eBay OpenAPI specs and regenerate types:

pnpm run sync && pnpm run typecheck && pnpm run build

Review the diff, commit changes you want to keep, and deploy.

Env management

pnpm run env:encrypt   # encrypt .env for safe sharing
pnpm run env:decrypt   # decrypt

Logging

EBAY_LOG_LEVEL=debug             # error | warn | info | debug
EBAY_ENABLE_FILE_LOGGING=true    # write logs to files

---

Validation architecture

The hosted backend includes a validation pipeline for item evaluation. Routes live in src/server-http.ts, logic in src/validation/.

Module layout:

File	Purpose
types.ts	Request/response contracts
effective-context.ts	Source-aware normalization (item vs event runs)
run-validation.ts	Orchestration entrypoint
recommendation.ts	Buy/track decision logic
providers/ebay.ts	Live browse-market snapshot
providers/ebay-sold.ts	Sold-data enrichment (temporary external provider)
providers/terapeak.ts	Terapeak / eBay Research metrics
providers/ebay-research.ts	Authenticated eBay Research fetcher
providers/social.ts	Twitter/X, YouTube, Reddit signals
providers/chart.ts	Chart-signal stub
providers/research.ts	Historical comeback research (Perplexity)

Flow: Admin calls /validation/run → server resolves runner user → orchestrator queries all providers → merges signals → returns writes + decision + debug metadata.

Merge precedence: Terapeak > sold provider > browse provider for overlapping fields. Optional providers (social, research) only write when data resolves — never blank existing values.

Known limitations:

• Sold-data provider is temporary (external API via RAPIDGATE_API_URL)
• Social signals are supportive only — not authoritative buy triggers
• Chart provider is a stub
• eBay Research requires valid Playwright session

eBay Research session management:

• Bootstrap: pnpm run research:bootstrap
• Inspect: pnpm run research:inspect-session
• Browser check: pnpm run research:check-browser
• Session source precedence: KV → env vars → local files → fallback
• QStash alerts: 24h before, 6h before, and at expiry → Telegram

---

Testing & validation

# Build and test
pnpm run build && pnpm run typecheck && pnpm test

# Connectivity check
pnpm run diagnose

# Hosted health
curl https://your-server.com/health

# Session check
curl -H "Authorization: Bearer <token>" https://your-server.com/whoami

# Validation runner health
curl https://your-server.com/sandbox/validation/health \
  -H "X-Admin-API-Key: YOUR_ADMIN_API_KEY"

# Privileged MCP admin-key bypass check
curl https://your-server.com/sandbox/mcp \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Accept: application/json, text/event-stream"

# MCP auth challenge test
curl -X POST https://your-server.com/sandbox/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → 401 with authorization_url

---

Troubleshooting

Hosted MCP returns 406

Include Accept: application/json, text/event-stream header.

OAuth callback: "Invalid or expired OAuth state"

OAuth state expires in 15 minutes. Restart the browser flow.

Token verification fails on refresh token

Refresh tokens expire after ~18 months or can be revoked. Run pnpm run setup or start new browser OAuth at /oauth/start.

Session token no longer works

# Check status:
curl -H "Authorization: Bearer <token>" https://your-server.com/whoami

# Revoke if exposed:
curl -X POST https://your-server.com/admin/session/<token>/revoke \
  -H "X-Admin-API-Key: YOUR_ADMIN_API_KEY"

Validation health is degraded

curl https://your-server.com/sandbox/validation/health \
  -H "X-Admin-API-Key: YOUR_ADMIN_API_KEY"

Check: VALIDATION_RUNNER_USER_ID set, runner has stored tokens, tokens not expired, RAPIDGATE_API_URL configured.

eBay Research shows authState = missing

pnpm run playwright:install
pnpm run build
pnpm run research:check-browser
pnpm run research:bootstrap

Expected after bootstrap: authState = loaded, sessionStrategy = storage_state, sessionSource = kv, authValidationSucceeded = true.

Stale MCP sessions after deployment

After deploying new code, agents' MCP sessions may still point to old container code. Agents must restart their MCP session (/reset or reopen chat) to negotiate a fresh connection.

---

Security checklist

• Do not commit .env or session tokens
• Protect /oauth/start with OAUTH_START_KEY, /admin/* and /validation/* with ADMIN_API_KEY
• Keep ADMIN_API_KEY long, random, server-side only, and separate from user session tokens; it also works as a privileged MCP Bearer-token bypass
• Keep /oauth/callback publicly reachable (eBay redirects here)
• Keep /health reachable for deployment health checks
• Rotate exposed eBay credentials and update secret file
• For production isolation, consider Cloudflare Access on /, /oauth/start, /admin/*

---

Resources

• eBay Developer Portal
• MCP Documentation
• Auth Configuration Guide
• OAuth Quick Reference
• API Status
• Changelog
• Contributing Guidelines
• Security Policy

---

License

MIT — see LICENSE