Skip to main content
dealdash-agent-bridge is the repo-local plugin that gives MCP-capable agents a safe DealDash tool surface. It is designed for Claude Code, OpenAI/Codex or ChatGPT MCP clients, OpenClaw, and future agent hosts. OpenClaw is treated as an optional WhatsApp and Telegram adapter, not as the core identity of the system. Human operators should start with Connect An AI Agent or the in-app /tools/ai-agent-setup page. This page is the agent-optimized reference for exact tool names, auth headers, and safety rules.

​
Architecture

  1. DealDash agent core: canonical /api/agent/* backend contract with acting-user scoped access.
  2. MCP server: provider-neutral stdio server in /plugins/dealdash-agent-bridge/scripts/server.ts.
  3. Channel adapters: optional messaging integrations that normalize attachments, capture approvals, and apply channel tone.

​
Backend Auth

Normal user setup uses login-link auth:
  1. The MCP bridge calls POST /api/agent/auth/start.
  2. The agent sends the returned DealDash approval link to the user.
  3. The user opens the link, signs in, and approves.
  4. The bridge polls GET /api/agent/auth/status/:requestId?deviceCode=....
  5. After approval, the bridge stores the scoped token inside the MCP process.
If the agent does not yet have the MCP bridge installed but can make HTTPS requests, it may start the same flow directly: 
curl -fsS -X POST https://dealdash.neonoir.ai/api/agent/auth/start \
  -H 'content-type: application/json' \
  --data '{"actorId":"openclaw-agent","channel":"openclaw:setup"}'
The agent should send only auth.authorizeUrl to the user, keep auth.deviceCode and any approved token inside its tool/session state, and poll auth.statusEndpoint after the user approves. A normal user setup must not be blocked on DEALDASH_AGENT_SERVICE_SECRET, DEALDASH_AGENT_DEFAULT_USER_ID, or deployment provider settings. Operator-managed adapters can still use gateway-delegated authentication.
  • Authorization: Bearer <DEALDASH_AGENT_SERVICE_SECRET>
  • x-dd-acting-user-id
  • x-dd-channel
  • x-dd-actor-id
  • x-dd-request-id
  • x-dd-approval-id for sensitive writes
The backend enforces acting-user scope before any proxied app route runs. Login approval links are generated from APP_ORIGIN first, then deployment fallback origins if needed; the short-link domain is not the preferred approval origin. Operators can verify the safe bring-your-own-agent surface inside DealDash at /settings -> AI Agent Connection. The Settings card shows connection status, .mcp.json path, MCP command, login-link endpoints, permission tiers, tool families, and recent scoped logs without exposing secret values. The public DealDash Agent Kit repository is djasha/dealdash-agent-kit. It contains sanitized Markdown instructions, skill files, and MCP setup notes for agents. It must never contain real secrets, user data, production tokens, database URLs, or private local paths.

​
Tool Families

  • Short links: create from URL, list, stats, delete
  • Screenshots: upload photo, capture URL, reserve, link to deal, get, latest, delete
  • Deals: search, get, latest, create, update, find by URL, due views, view logs, progress
  • Payments: list, create, update, delete
  • Tasks: list, latest, create, complete, reopen
  • Contacts: search, get, latest, upsert, by phone, deals, notes, labels, counts, duplicates
  • Influencers: search, get, latest, upsert, by phone, by promo code, stats, last progress
  • Activity: feed and analytics
  • Suggestions: pipeline summary, next actions, payment followups, content followups
  • Context: search and resource hints
  • Memory: list, create, archive
  • Approvals: request and status

​
MCP Resources And Prompts

The MCP server exposes fixed resources for hosts that support resources/read:
  • dealdash://context/search: default search across recent accessible DealDash context.
  • dealdash://linkshot/view-logs: recent LinkShot View Logs.
  • dealdash://memory/active: active human-visible agent memory.
The MCP server also exposes prompts:
  • dealdash_read_only_start: start with context search, screenshots, View Logs, and due views.
  • dealdash_image_to_link: guide a safe image upload and short-link return flow.
Use resources for context, prompts for guided workflows, and tools for actions.

​
Approval Tiers

  • Tier 0: reads only
  • Tier 1: low-risk writes such as short-link creation, screenshot upload, screenshot linking, task state changes, and note creation
  • Tier 2: sensitive writes such as deal create/update/delete, payment CRUD, contact deletes, screenshot deletes, and visibility changes
Tier 2 calls require an approved x-dd-approval-id. For OpenClaw messaging flows, Telegram approval evidence should be captured by the adapter before confirming the approval record. Confirmation is not exposed as a generic MCP tool and requires DEALDASH_AGENT_APPROVAL_CONFIRM_SECRET plus x-dd-approval-confirm-secret.

​
V1 Exclusions

V1 intentionally does not expose admin/auth/team tools, runtime execution, filesystem tools, or bulk destructive operations. URL screenshot capture accepts only http and https URLs and blocks local/private targets by default. Use DEALDASH_AGENT_ALLOW_PRIVATE_CAPTURE_URLS=true only for trusted development capture. Photo uploads accept PNG, JPEG/JPG, WebP, GIF, AVIF, and BMP raster images by default. The MCP bridge enforces DEALDASH_AGENT_MAX_IMAGE_BYTES before sending the payload to DealDash. The current default binary image limit is 40MB; the DealDash API JSON body limit has 64MB headroom for base64 encoding. Raise those limits only in controlled deployments because base64 uploads are memory-heavy. SVG, HEIC, and TIFF are not accepted by default. SVG can contain active content, and HEIC/TIFF are not reliably previewable in browser-based DealDash screenshot galleries. Messaging adapters should convert those formats to PNG/JPEG/WebP before calling screenshots.upload_photo.

​
LinkShot View Logs

deals.view_logs is a Tier 0 read operation routed through /api/agent/deals/view-logs. It mirrors the website’s /screenshots View Logs tab and supports scope, dealId, videoId, from, to, q, limit, and offset filters. The bridge applies the same acting-user boundaries as the DealDash website: owned records are visible by user ID, team-shared deal logs require active team membership and deal sharing, and screenshot previews are included only when the acting user owns or can explicitly view the screenshot.

​
Context Search And Memory

Use context.search before guessing exact IDs. It searches deals, screenshots, LinkShot logs, short links, contacts, influencers, and active memory. Useful filters:
  • q: text query
  • scope: mine or mine-and-shared
  • types: comma-separated list such as deals,screenshots,view_logs,memory
  • limit and offset
Search results include a resourceUri, web link when available, access/ownership context, and metadata. Shared data still follows website sharing rules. Use memory.create only after telling the user the exact title, content, tags, and source you will save. Memory is visible, account-scoped, and searchable through context.search. Use memory.archive to remove stale memory from active context. Do not promise permanent deletion in V1.

​
Related Settings Page

See AI Agent Connection Settings for the in-app BYOA endpoint, Settings UI, security rules, and test map.