SignalOps
Engineering guide

How SignalOps uses MCP tools for agentic commerce recovery.

Model Context Protocol gives the SignalOps agent a typed way to inspect evidence, call internal tools, run approved connector actions, and return with proof instead of acting like a chat box.

Published for developers and operators evaluating how SignalOps turns commerce signals into controlled recovery work.

DetectFind a product, refund, repeat purchase, or campaign leak. DecideCall a typed MCP tool with the right context. ActExecute only after permission and connector checks pass. ProvePoll results and compare the next run to baseline.
SignalOps MCP agent tool architecture diagram
The agent reasons over commerce evidence, then calls typed MCP tools that wrap SignalOps services and connector APIs.

What MCP gives an agent

Model Context Protocol is a client-server protocol for connecting AI applications to external context and actions. In plain terms, it gives an agent a standard way to discover tools, read resources, use prompts, and exchange messages through a structured protocol instead of hard-coded one-off integrations.

That matters because a commerce recovery agent should not guess how to pause a campaign, draft an email, update a product, or compare a follow-up run. It should call an explicit tool with an input schema, receive structured output, and leave an audit trail.

SignalOps rule: MCP is the agent's workbench. OAuth connectors and backend services still own merchant data access, permission checks, and execution.

The architecture shape

MCP uses a host, client, and server pattern. The host is the AI application. The client manages one protocol connection. The server exposes capabilities such as tools and resources. The data layer uses JSON-RPC messages, while the transport layer handles how those messages move between the client and server.

In SignalOps, the important mapping is simple:

MCP conceptSignalOps mappingWhy it matters
HostThe agent runner or external AI hostDecides which tool should be used for the current recovery job.
ClientThe protocol session created by the hostLists tools, sends tool calls, and receives structured results.
ServerSignalOps MCP endpointExposes commerce-safe tools backed by SignalOps services.
ToolsExecutable recovery functionsSync audiences, draft campaigns, prepare product edits, poll results, compare metrics.
ResourcesReadable contextLatest diagnosis, queue state, product leak context, prior actions, evidence history.
PromptsReusable task patternsKeep recovery plans and merchant reports consistent without turning them into static copy.

Why not just call APIs directly?

Direct APIs are still necessary. Shopify, Klaviyo, Google Ads, Jumia, and email providers are reached through OAuth and platform APIs. MCP does not replace those connectors. It sits one layer above them so the agent sees a consistent set of tools regardless of which connector exists for the merchant.

That layer lets SignalOps handle missing connectors gracefully. If a merchant has Klaviyo but no Google Ads, the agent can still sync an audience and watch repeat purchase or refund movement. If Shopify is missing but the brand uses the ingestion API, the agent can still reason from normalized orders and product records.

The first SignalOps MCP tools

The first useful toolset is not a huge catalog. It is the smallest set that lets the agent move from evidence to action to proof.

get_active_recovery_jobsFind jobs that need drafting, execution, polling, or follow-up comparison.
get_flow_contextLoad the audience, product, metric, and prior diagnosis behind a flow.
generate_email_draftCreate merchant-specific recovery copy from the flow context.
sync_klaviyo_campaignCreate or update the Klaviyo audience and campaign draft after approval.
poll_klaviyo_campaignRefresh campaign performance and attach evidence to the job.
compare_followup_metricCompare baseline and follow-up runs to decide whether the action improved the metric.
prepare_shopify_product_updateFetch product context and produce a proposed edit before merchant approval.
execute_approved_actionRun only actions that already passed SignalOps approval checks.

What happens after a leak is found

A useful agent must remember what it did. If it creates a campaign, it should store the campaign ID. If it updates product copy, it should store what changed. If it saves a baseline refund rate, it should compare the next run against that exact baseline.

SignalOps MCP recovery sequence diagram
The recovery loop records evidence at each step so the dashboard rail and Monday report can explain the result.
  1. SignalOps detects a leak and writes an action card.
  2. The agent runner asks MCP for active recovery jobs.
  3. The agent calls the right context and drafting tools.
  4. If approval is needed, SignalOps stores the proposed action and waits.
  5. Once approved, the execution tool calls the connector service.
  6. The agent stores external IDs, such as a Klaviyo campaign ID or Shopify product ID.
  7. A scheduled runner polls external results and compares the next diagnosis run.
  8. The rail and report summarize baseline, action, follow-up, and confidence.

Safety is not delegated to the model

The agent can propose work, but SignalOps enforces the work boundary. Risky actions require the right merchant plan, connector permission, stored approval, and a scoped execution payload. This prevents a generated plan from becoming an unchecked store change.

{
  "tool": "execute_approved_action",
  "input": {
    "recommendation_id": 79,
    "expected_connector": "klaviyo",
    "expected_action_type": "klaviyo_campaign_draft"
  },
  "guardrails": [
    "merchant owns recommendation",
    "approval_status is approved",
    "connector token exists",
    "payload has evidence and rollback note"
  ]
}

The agent receives the result, but the backend decides whether execution is allowed.

Why the dashboard rail matters

An agentic product should not hide work inside logs. The merchant needs a compact operator summary: what the agent found, what it did, what it is watching, and when proof will exist. That is why SignalOps saves an operator payload after each MCP-backed action.

{
  "status": "watching_followup",
  "headline": "Saved the baseline for this approved recovery action.",
  "latest_evidence": "Refund rate baseline: 31%. Klaviyo recovery flow executed.",
  "next_action": "When the next run arrives, compare refund rate automatically."
}

The UI can turn that into a short human report instead of showing raw internal fields.

The target behavior

The long-term target is an operator that earns trust by doing useful work in small, auditable steps:

  • Find a leak.
  • Quantify the money at risk.
  • Propose the action with evidence.
  • Request approval when the action changes a merchant system.
  • Execute through the connector.
  • Poll the external result.
  • Compare the follow-up run.
  • Report recovered value and confidence.
Bottom line: MCP helps SignalOps make the agent operational, not conversational. The agent does not just answer the merchant. It works through tools, records evidence, and comes back with a result.