Which integrations are available for this server?

Allows ChatGPT to call the get_offers tool to fetch live structured product offers in real time.

How do I use Offer Discovery MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Offer Discovery MCP Server find me the latest offers on electronics" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Offer Discovery MCP Server

by siddharthkoundal

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Offer Discovery MCP Server

A Model Context Protocol (MCP) server that connects AI agents to a live offers API and returns structured product offers in real time.

Related MCP server: Agentic Product Protocol MCP Server

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI models (like ChatGPT) call external tools and fetch live data — designed specifically for LLM tool use.

ChatGPT ──────── MCP Protocol ────────► MCP Server ────► Offers API
         "call get_offers tool"         (this repo)       (live, 520+ offers)
         ◄──────────────────────────────              ◄──────────
              Returns structured JSON

When a user asks ChatGPT "What home improvement deals are available?", ChatGPT automatically:

Recognizes it needs real data
Calls our get_offers tool via MCP
Receives a structured JSON list of live offers
Summarizes and presents them to the user

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                                  │
│                                                                      │
│   ChatGPT / AI Agent / MCP Inspector                                │
│   (Sends JSON-RPC tool call requests)                               │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ MCP Protocol (JSON-RPC 2.0)
                            │
              ┌─────────────▼──────────────┐
              │      TRANSPORT LAYER        │
              │                            │
              │  stdio (local/dev)         │  ← src/index.ts
              │  HTTP + SSE (remote/ngrok) │  ← src/server.ts
              └─────────────┬──────────────┘
                            │
              ┌─────────────▼──────────────────────────┐
              │   McpServer  (SDK v1.x high-level API)  │
              │                                         │
              │  registerTool("get_offers", {            │
              │    inputSchema: GetOffersInputZodShape,  │  ← offerSchema.ts
              │    description: "...",                   │
              │  }, handler)                            │
              │                                         │
              │  • Serves  tools/list  automatically   │
              │  • Validates args via Zod automatically │
              │  • Routes  tools/call  to handler       │
              └─────────────┬───────────────────────────┘
                            │ pre-validated GetOffersInput
              ┌─────────────▼──────────────┐
              │       API CLIENT LAYER      │
              │                            │
              │  fetchOffers()             │  ← src/api/offersClient.ts
              │  Live API + mock fallback  │
              └─────────────┬──────────────┘
                            │ axios.get()
              ┌─────────────▼──────────────┐
              │      OFFERS API            │
              │  api.example.com/offers    │
              │  /offers?campaignMappingId │
              │  =ALL   (live offers)      │
              └────────────────────────────┘

Project Structure

offer-discovery-mcp/
│
├── src/
│   ├── index.ts                  # Entry point: stdio transport (local dev & MCP Inspector)
│   ├── server.ts                 # Entry point: HTTP/SSE transport (ngrok & remote clients)
│   │
│   ├── schemas/
│   │   └── offerSchema.ts        # Zod schemas: input args + offer output shape
│   │
│   ├── api/
│   │   └── offersClient.ts       # Live API client: calls the offers API, falls back to mock
│   │
│   └── tools/
│       └── getOffers.ts          # Tool handler: validate → fetch → filter → format → respond
│
├── package.json                  # Dependencies + npm scripts
├── tsconfig.json                 # TypeScript: ES2022, NodeNext, strict mode
├── .gitignore
├── README.md                     # ← You are here
└── TESTING.md                    # Step-by-step testing guide

Data Flow

Exact journey of a single tool call from ChatGPT to a response:

1. ChatGPT sends:
   { "method": "tools/call", "params": { "name": "get_offers", "arguments": { "category": "furniture", "featured": true } } }

2. src/index.ts (or server.ts) — McpServer receives the tool call
   └── SDK validates args against GetOffersInputZodShape (Zod)
       ├── FAIL → SDK returns validation error to ChatGPT (handler not called)
       └── PASS → calls the registered handler with typed GetOffersInput args

3. src/tools/getOffers.ts :: handleGetOffers(args: GetOffersInput)
   └── calls fetchOffers(args)

4. src/api/offersClient.ts :: fetchOffers()
   ├── axios.get("https://api.example.com/offers?campaignMappingId=ALL")
   │   ├── SUCCESS → live offers returned
   │   └── FAIL    → falls back to MOCK_OFFERS (server stays functional)
   └── Applies in-process filters:
       industry → category (legacy) → offerType → region → network → brand → featured → pagination
       └── Returns: Offer[]

5. src/tools/getOffers.ts :: formatOfferForChatGPT()
   └── Strips raw image URLs + internal IDs
       └── Surfaces: brand, offerType, links, keywords, expiryMsg, disclosure
       └── Wraps in envelope: { totalOffers, appliedFilters, offers: [...] }

6. ChatGPT receives the JSON and presents live offers to the user.

Transport Modes

Mode	File	Command	Use When
stdio	`src/index.ts`	`npm run dev`	Local MCP Inspector, Claude Desktop
HTTP/SSE	`src/server.ts`	`npm run dev:http`	Remote access via ngrok, ChatGPT Agents SDK

Endpoints (HTTP mode)

Endpoint	Method	Purpose
`POST /mcp`	Streamable HTTP	OpenAI Responses API (recommended)
`GET /mcp`	Streamable HTTP	SSE streaming for long responses
`GET /sse`	SSE (legacy)	MCP Inspector
`POST /messages`	SSE (legacy)	MCP Inspector message routing
`GET /health`	—	Health check

OpenAI Integration

Source: OpenAI Apps SDK — Build your MCP server · MCP concept overview

Recommended Transport: Streamable HTTP

Per official OpenAI docs, Streamable HTTP is the recommended transport for production.

Transport	Status	Use When
`stdio`	✅ Active	Local MCP Inspector, Claude Desktop
`SSE`	⚠️ Legacy	Remote testing with MCP Inspector
`Streamable HTTP`	✅ Recommended	Production (ChatGPT, OpenAI Responses API)

Both transports are implemented in this project. POST /mcp uses Streamable HTTP; GET /sse uses legacy SSE.

Tool Annotations (Required for ChatGPT App Store)

server.registerTool("get_offers", {
  description: "...",
  inputSchema: GetOffersInputZodShape,
  annotations: {
    readOnlyHint: true,      // ✅ reads data only, never writes
    openWorldHint: false,    // ✅ scoped to the offers domain only
    destructiveHint: false,  // ✅ no deletes or irreversible actions
  },
}, handler);

Official References

Resource	Link
OpenAI Apps SDK: Build MCP server	developers.openai.com/apps-sdk/build/mcp-server
MCP concept overview	developers.openai.com/apps-sdk/concepts/mcp-server
TypeScript SDK	github.com/modelcontextprotocol/typescript-sdk
MCP Specification	spec.modelcontextprotocol.io
MCP Inspector	modelcontextprotocol.io/docs/tools/inspector

Getting Started

Prerequisites

Node.js v18+
npm v9+
ngrok (only for remote/HTTP mode)

Installation

git clone https://github.com/siddharthkoundal/chatgpt-marketplace-app.git
cd offer-discovery-mcp
npm install

Running Locally (stdio — for MCP Inspector)

npm run dev

Running for Remote Access (HTTP — for ChatGPT / ngrok)

# Terminal 1: Start HTTP server
npm run dev:http
# → 🚀 offer-discovery-mcp v1.0.0 running on port 3000
# → [offer-discovery-mcp] Offers API working! returned live offers.

# Terminal 2: Expose via ngrok
ngrok http 3000
# → Forwarding: https://abc123.ngrok-free.app → localhost:3000

See TESTING.md for detailed testing steps.

Available Scripts

Command	Description
`npm run dev`	Start server with stdio transport (local MCP Inspector)
`npm run dev:http`	Start server with HTTP/SSE transport (ngrok / remote)
`npm run build`	Compile TypeScript to `dist/`
`npm start`	Run compiled JS from `dist/`

Environment Variables

Create a .env file in the project root (already listed in .gitignore — never commit it):

# Offers API
OFFERS_API_URL=https://api.example.com/offers
OFFERS_API_KEY=your-api-key-here

# Server
PORT=3000

tsx (used by npm run dev and npm run dev:http) loads .env automatically — no extra packages needed.

If OFFERS_API_KEY is missing or empty, the server falls back to the MOCK_OFFERS dataset automatically.

Available Tools

1 tool

get_offersA

Fetches structured offers from a live offers API (prototype). Filter by: industry, offer type, region, network, brand, or featured status. Use 'category' for a free-text keyword search across industry and brand names.

ParametersJSON Schema

Name	Required	Description
`brand`	No	Filter by brand/merchant name (e.g. 'Ashley', 'Sam's Club').
`offset`	No	Pagination offset (non-personalized only).
`region`	No	Filter by region. Valid values: MIDWEST, NORTHEAST, SOUTH, SOUTHEAST, WEST
`network`	No	Filter by partner network. Valid values: AUTO PARTNER, HOME PARTNER, FLOORING PARTNER, POWERSPORTS PARTNER
`category`	No	Product category keyword (e.g. 'furniture', 'electronics'). Maps to industry filter.
`featured`	No	If true, return only featured brand offers.
`industry`	No	Filter by industry. Valid values: FURNITURE, ELECTRONICS & APPLIANCES, HEALTHCARE & OPTICAL, HEALTH & WELLNESS, HEATING & AIR CONDITIONING, HOME IMPROVEMENT, JEWELRY, LAWN & GARDEN, MUSIC
`maxPrice`	No	Legacy price filter — not applicable to the real API (financing offers have no list price). Kept for backward compat.
`offerType`	No	Filter by offer type. Valid values: DEALS, FINANCING OFFERS, EVERYDAY VALUE
`limitOffersCount`	No	Max number of offers to return (non-personalized only).

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must convey behavioral traits. It notes the prototype status and warns that maxPrice is legacy, but does not disclose idempotency or side effects (likely read-only). Some useful context, but not fully comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and filters, no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the basic purpose and filters, but does not describe output structure, default behavior, or pagination usage. Given the complexity (10 params, no output schema), more detail would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters (100%), but the description adds value by clarifying that 'category' performs a free-text search across industry and brand names, which is not obvious from schema alone. This goes beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches structured offers from a live API and lists the supported filters, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions key filter parameters and explains that 'category' performs a free-text search, providing helpful usage hints. However, it does not specify when not to use this tool or alternatives, which is acceptable given no siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev1.0.0Jul 17, 2026
- First observedget_offers

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-07-17 09:42 across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity between tools. The tool's purpose is clearly defined.

Naming Consistency5/5

The single tool uses a clear verb_noun pattern (get_offers), which is consistent with common MCP conventions. No naming conflicts exist.

Tool Count3/5

A single tool feels thin for a server named 'Offer Discovery MCP Server', which might reasonably include multiple tools (e.g., get_offer_details, search_offers). However, as a prototype, it is borderline acceptable.

Completeness2/5

The server only provides a single fetch operation with filters, lacking essential discovery features such as retrieving a specific offer by ID, pagination, or detail views. This leaves significant gaps for typical offer discovery workflows.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

agent-commerce
ai.petraport
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
E-commerce & Retail Search
2
shop-search B
io.github.sangha-lightanchor
Product search for AI agents: Amazon + Shopify, cart-to-checkout buy path. Pay-per-call, no API key.
E-commerce & Retail Search
21
Agentic Shelf A
ai.agenticshelf
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
E-commerce & Retail Search
2
signals A
com.rivalsweeper
Beta. Pay-per-call eCommerce competitive intel for AI agents: pricing, promos, readiness & more.
E-commerce & Retail Marketing
102

Related MCP Servers

AgentShare — Solana DeFi
Blockchain Data Platforms Finance
anhmtk
A
license
A
quality
C
maintenance
AgentShare delivers structured product search and pricing signals for AI agents over REST and MCP (Streamable HTTP). Responses include freshness & coverage metadata so agents can reason about data recency. API keys secure billed endpoints; public discovery at /agent.json and /mcp.json. Currently integrates connected marketplaces and affiliate feeds – roadmap expands to global e-commerce (AliExpre
Updated 19 hours ago (2026-09-16 12:49 UTC)
4
1
MIT
Agentic Product Protocol MCP
E-commerce & Retail Search
AiAgentKarl
A
license
A
quality
D
maintenance
Klarna-style product discovery for AI shopping agents. Makes product catalogs machine-readable so AI agents can search, compare, and purchase products programmatically.
Updated 6 months ago (2026-03-20 11:47 UTC)
6
MIT
dentro MCPofficial
E-commerce & Retail Search
dentro-fyi
A
license
A
quality
D
maintenance
Provides structured commerce data for AI agents, enabling real-time product searches and brand discovery across 22,000+ DTC brands without scraping or hallucination.
Updated 5 months ago (2026-04-29 12:25 UTC)
5
19 npm
MIT
Merchant Web MCP
E-commerce & Retail Autonomous Agents
Redser06
A
license
Not graded
quality
C
maintenance
Enables AI shopping agents to search products, check stock, apply promotions, manage cart sessions, and create cryptographically signed checkout sessions on e-commerce storefronts, while giving merchants analytics into agent intent and catalog demand gaps.
Updated 21 days ago (2026-08-26 22:29 UTC)
MIT

Offer Discovery MCP Server

Table of Contents

What is MCP?

Architecture Overview

Project Structure

Data Flow

Transport Modes

Endpoints (HTTP mode)

OpenAI Integration

Recommended Transport: Streamable HTTP

Tool Annotations (Required for ChatGPT App Store)

Official References

Getting Started

Prerequisites

Installation

Running Locally (stdio — for MCP Inspector)

Running for Remote Access (HTTP — for ChatGPT / ngrok)

Available Scripts

Environment Variables

Available Tools

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

AgentShare — Solana DeFi

Agentic Product Protocol MCP

dentro MCPofficial

Merchant Web MCP