Haraj Model Context Protocol (MCP) Server

A production-grade Model Context Protocol (MCP) server for Haraj, built for Next.js, Vercel Serverless, and Supabase. Connects AI models (such as ChatGPT) to Haraj accounts for listing management, marketplace discovery, messaging, image processing, and bulk operations.

Features

• Multi-User OAuth 2.0 and DCR: Built-in Dynamic Client Registration (RFC 7591) and Client ID Metadata Document support. Allows instant one-click connection in AI clients without manually setting client IDs or client secrets.

• Persistent Serverless Storage: Integrated with Supabase PostgreSQL to persist multi-user sessions, authorization codes, and refresh tokens across stateless Vercel Serverless invocations.

• Marketplace Intelligence: Search listings across Haraj, compute market price distributions (median, cheapest, highest, outliers), and generate optimized listing titles and descriptions.

• Buyer Conversations: Inspect buyer contact inquiries, draft responses, and send replies securely with mandatory user confirmation and idempotency protection.

• Security Auditing: Structured audit log tracking for all write actions, session revocation, permissions checking, and full ad snapshot exporting and restoration.

• Interactive Chat Widgets: Provides custom HTML/JS widgets for real-time listing cards, engagement dashboards, and sign-in management within supported AI clients.

Related MCP server: Salla MCP Server

How to Get Your Haraj Session Token

To connect your Haraj account, obtain your JWT session token using any of the following methods:

Method 1: Chrome / Browser DevTools (Recommended)

1. Open haraj.com.sa in your web browser and sign in.

2. Press F12 (or right-click and select Inspect) to open Developer Tools.

3. Select the Network tab.

4. Refresh the page or click any section.

5. Click any request sent to graphql.haraj.com.sa under the Network list.

6. Look under Request Headers for Authorization: Bearer eyJ....

7. Copy the token string starting with eyJ... (exclude the word Bearer ).

Method 2: Application Storage

1. Open Developer Tools (F12) on haraj.com.sa.

2. Go to the Application tab (or Storage tab in Firefox).

3. Expand Local Storage and select https://haraj.com.sa.

4. Look for the key named haraj_token or token.

5. Copy the value string starting with eyJ....

How to Connect Deployed Server to LLMs and AI Clients

Once your Vercel deployment URL (for example https://your-app-domain.vercel.app) is live, connect your AI client using one of the following methods:

Option 1: Connecting ChatGPT / Web-Based AI Clients

1. Open your AI client settings or Custom GPT configuration page.

2. Add a new Model Context Protocol (MCP) tool server.

3. Enter your deployed server endpoint: https://your-app-domain.vercel.app/mcp

4. When prompted for authorization, the server uses Dynamic Client Registration (DCR) automatically.

5. If a sign-in card or link is returned, click the link to open your server login page.

6. Paste your Haraj Session Token starting with eyJ... and click Save & Connect.

Option 2: Connecting Claude Desktop / Local MCP Clients

Add the server to your local MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "haraj": {
      "command": "npx",
      "args": ["-y", "haraj-private-mcp"],
      "env": {
        "HARAJ_TOKEN": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
      }
    }
  }
}

Option 3: Connecting Antigravity IDE / Cursor / AGY CLI

Add the Streamable HTTP transport URL to your workspace .gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "haraj-mcp": {
      "url": "https://your-app-domain.vercel.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Deployment Guide (Vercel + Supabase)

Step 1: Create Supabase Table

In your Supabase project SQL Editor, run:

create table if not exists public.haraj_sessions (
  subject text primary key,
  data jsonb not null,
  updated_at timestamp with time zone default timezone('utc'::text, now()) not null
);

Step 2: Configure Environment Variables

Set the following environment variables in your Vercel Project Settings:

NEXT_PUBLIC_SUPABASE_URL=https://your-supabase-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-supabase-anon-key
SUPABASE_SECRET_ROLE_KEY=your-supabase-service-role-key
OAUTH_ISSUER=https://your-app-domain.vercel.app
OAUTH_SIGNING_SECRET=your-random-32-byte-signing-secret

Step 3: Deploy to Vercel

git push origin main

Vercel automatically detects the configuration from vercel.json and deploys your serverless MCP endpoints.

Complete Tool Directory

Marketplace & Intelligence

• haraj_search_marketplace: Search all public listings across Haraj platform, filter by city/price, and find market deals.

• haraj_compare_market_prices: Compute price statistics (median, cheapest, highest, outliers) and suggest competitive pricing.

• haraj_suggest_listing: Generate optimized titles and structured description text based on top market competitors.

Messaging & Conversations

• haraj_list_conversations: List buyer conversations filtered by ad ID or unread status.

• haraj_get_conversation: Retrieve complete message thread history for a specific buyer and listing.

• haraj_draft_reply: Save response draft for user review before sending.

• haraj_send_reply: Send confirmed reply to buyer with mandatory confirmation and idempotency token.

• haraj_list_messages: View buyer contact inquiries on owned listings.

• haraj_get_chat: Retrieve buyer inquiry details.

• haraj_reply_message: Send direct message response.

Security, Admin & Auditing

• haraj_session_expiry: Check exact expiration timestamp, token fingerprint, and renewal status.

• haraj_revoke_sessions: Disconnect account and clear stored session records across memory and database layers.

• haraj_audit_log: View structured audit log history for all write and edit operations.

• haraj_permissions: Check active security permissions and scopes assigned to the session.

• haraj_test_connection: Execute API ping diagnostic to measure response latency and upstream health.

• haraj_session_status: Verify session connectivity and current account owner.

• haraj_whoami: Resolve identity claims and verified username.

• haraj_login_link: Generate one-time session sign-in URL.

• haraj_logout: Disconnect current session.

• haraj_server_health: Check server build version and widget registrations.

Ad Management & Quality

• haraj_list_ads: Fetch pageable list of user listings.

• haraj_get_ad: Retrieve single ad details, body text, and images.

• haraj_find_ads: Search and rank user ads across pages.

• haraj_ad_doctor: Diagnose quality issues and receive prioritized fix lists.

• haraj_show_ads: Render interactive UI card list of listings.

• haraj_show_ad: Render interactive UI detail card with engagement metrics.

Write & Editing

• haraj_validate_ad: Test ad content validity before publishing.

• haraj_create_ad: Publish new listing to Haraj with user confirmation.

• haraj_edit_ad: Edit listing title, price, body, or photos (supports dry-run mode).

• haraj_refresh_ad: Bump ad to top of search results (with cooldown protection).

• haraj_get_refresh_eligibility: Check whether ad is eligible for refresh bump.

Bulk Operations

• haraj_bulk_refresh: Refresh multiple listings in parallel with rate-limit handling.

• haraj_bulk_stats: Fan-out performance stats across account listings.

• haraj_bulk_edit: Edit price or content across multiple listings simultaneously.

• haraj_bulk_doctor: Run health diagnostics across all account listings.

Image Pipeline

• haraj_upload_image: Process, resize, and upload single JPEG/PNG/WebP image to Haraj storage.

• haraj_upload_images: Upload multiple images in parallel.

• haraj_attach_images: Attach uploaded image references to existing listing.

Snapshots & Backups

• haraj_export_ads: Export full ad metadata and image links to JSON format.

• haraj_restore_ad_snapshot: Preview or restore listing state from exported snapshot.

Verification

Run TypeScript compilation, linting, and unit tests:

npm run check

License

Distributed under the MIT License. See LICENSE for details.