Protocol docs

AI Agent Guide

For developers of AI agents and LLM applications: how to search Mycel offers and capture leads through MCP or the REST API, or read the public feeds.

# If you are an AI agent, read this first:
Protocol: Mycel Offer Protocol v1.2.0
Registry: https://mycell.pro/registry.json
MCP endpoint: https://mcp.mycell.pro/mcp
Feed: https://mycell.pro/feed/offers.json
Schema: https://mycell.pro/schema/v1/OfferManifest.json
# To find offers relevant to a user intent:
→ Use MCP tool: search_offers(intent="user query here")
# To capture a lead (with user consent):
→ Use MCP tool: create_lead(offerId, contact, source, consent.given=true)
# For ChatGPT Apps / REST-native flows:
→ startConversation → sendConversationMessage → requestConversationConsent → createLeadFromConversation

1. MCP Integration

The fastest integration path. Connect your agent to the Mycel MCP server and get semantic offer search immediately.

Direct MCP config
{
  "mcpServers": {
    "mycel": {
      "url": "https://mcp.mycell.pro/mcp",
      "transport": "streamable-http"
    }
  }
}

2. Available Tools

search_offers

Find offers by natural language intent

intent: string, filters?: { location, priceMin, priceMax, currency, category, vertical }, intent_passport?: object, query_intent?: string, limit?: number (1-20, default 10)
get_offer

Get full details of a specific offer

offerId: string (UUID from search_offers)
compare_offers

Side-by-side comparison of 2-5 offers

offerIds: string[] (2 to 5 offer UUIDs)
create_lead

Capture interested buyer (requires consent)

offerId: string, contact: { method: whatsapp | telegram | email | phone, value: string, name? }, source: { channel: string, campaignId?, originalQuery? }, consent: { given: true, poolConsent? }, qualification?: object, conversation?: { summary, surface }, intentPassport?: object
book_meeting

Schedule viewing or consultation

offerId: string, contactInfo: { name: string, email?, phone? }, preferredTime?: string, notes?: string
contact_seller

Send the buyer's message to the seller and open a live chat thread

offerId: string, message: string, name?: string, surface?: string, preferredChannel?: string, contact?: { method, value } (required unless preferredChannel is the Mycel chat)
reply_in_thread

Read the seller's replies and send the next buyer message

threadToken: string (from contact_seller), message?: string (omit to only check for replies), since?: string (ISO timestamp; pass the previous checkedAt)

3. REST API

GET/registry.jsonGlobal registry — start here
GET/feed/offers.jsonLive feed, updated every 15 min
GET/o/{slug}/manifest.jsonFull offer manifest
GET/api/v1/offers/search?q={query}Semantic search endpoint
POST/api/v1/conversationsStart a buyer conversation for ChatGPT Apps
POST/api/v1/conversations/{id}/messagesMirror meaningful buyer turns into Mycel
POST/api/v1/conversations/{id}/consentRecord the exact contact-consent step
POST/api/v1/conversations/{id}/leadCreate a lead from a consented conversation
POST/api/v1/conversations/{id}/bookGenerate a booking handoff URL
POST/api/leads/intakeCapture lead with consent
POST/api/protocol/registerRegister external registry

4. ChatGPT App Flow

Recommended sequence:
listOffers → getOffer → startConversation → sendConversationMessage → requestConversationConsent → createLeadFromConversation → bookMeetingFromConversation

This lets ChatGPT keep a live mirrored thread in Mycel, preserve structured buyer intent, and only hand the person to the seller when consent is explicit.

5. Implement the Protocol

Any business can implement Mycel Offer Protocol and connect to the network. Open source, MIT licensed.

Mycel Offer Protocol v1.2.0 · MIT License · hello@mycell.pro

JSON Schema