# @signaliz/mcp-server

The local stdio MCP adapter for Signaliz core products, Signal Awareness, and Signaliz Flow.

Campaign OS tools for Codex, Claude Code, Cursor, Devin, Grok, Signaliz Agent,
and other MCP-capable harnesses:

- `campaign_os_list_clients`
- `campaign_os_get_client_context`
- `campaign_os_search_knowledge`
- `campaign_os_get_provider_runtime`
- `campaign_os_start_build`
- `campaign_os_get_build`
- `campaign_os_create_draft`
- `campaign_os_refine_campaign`
- `campaign_os_create_audience_draft`
- `campaign_os_materialize_cache_audience`
- `campaign_os_upsert_audience_schedule`
- `campaign_os_preview_audience`
- `campaign_os_compile_preview`
- `campaign_os_plan_alpha`
- `campaign_os_start_alpha_discovery`
- `campaign_os_get_alpha_run`
- `campaign_os_start_alpha_validation`
- `campaign_os_get_alpha_validation_run`
- `campaign_os_apply_validated_alpha`
- `campaign_os_preflight_alpha_materialization`
- `campaign_os_start_alpha_materialization`
- `campaign_os_get_alpha_materialization`
- `campaign_os_list_connections`
- `campaign_os_create_source_binding`
- `campaign_os_preflight_source_binding`
- `campaign_os_submit_action_request`
- `campaign_os_prepare_action_preflight`
- `campaign_os_list_receipts`

`campaign_os_get_provider_runtime` describes the Clay plugin/Public API split
or Instantly agency/BYO route without returning credentials. Complete builds,
Audience drafts, no-spend previews, and compile previews run without CMM-admin
approval and cannot call Clay or Instantly. Cache-only materialization is capped
at 500 members and returns exact zero-provider/Clay usage plus a terminal
reconciliation receipt; callers provide a stable idempotency key for safe
retries and may supply `campaign_id` to link the run to an exact campaign.
Signaliz Alpha can return a zero-call research plan, run one source-cited
discovery from one saved immutable CampaignSpec with an exact $0.10 ceiling,
validate a candidate on 3-20 exact
entities with a $0.25 ceiling, and append a passing receipt to the immutable
CampaignSpec. A separate no-spend materialization preflight pins the exact
campaign, Audience run, validation receipt, coverage target, batches, and
research ceiling. Starting it requires `confirm_spend=true` plus the immutable
approval hash and authorizes only that bounded research. Agents cannot forge
validated status, and these tools cannot call Clay, create an audience, load or
activate a provider, queue, or send. Consequential action requests require a nonblank idempotency key and accept
only whitelisted non-secret `preflight_inputs`. Once a Signaliz superadmin
approves a request, `campaign_os_prepare_action_preflight` appends or reads one
immutable no-call continuation; it reports blockers without invoking the
downstream preflight. Always-on cache schedules return honest target-met, partial, or
no-change receipts without creating standing Clay approval. Paid sourcing, provider load,
activation, real-time arming, queueing, and sending remain separate requests.

- `find_email`
- `verify_email`
- `company_signal_enrichment`
- `check_job_status`
- `signal_to_copy`
- `signals_everything`
- `run_signaliz_flow`, `get_signaliz_flow`
- `signal_monitor_create`, `signal_monitor_bulk_create`, `signal_monitor_list`
- `signal_monitor_update`, `signal_monitor_run`, `signal_monitor_delete`
- `signal_monitor_signals`, `signal_monitor_export`
- `signal_monitor_settings`, `signal_monitor_set_output`, `signal_monitor_test_webhook`
- `signal_monitor_send_export`

```bash
claude mcp add signaliz \
  -e SIGNALIZ_API_KEY=sk_your_key \
  -- npx -y @signaliz/mcp-server --campaign-os
```

`--campaign-os` exposes only the thirty tenant-bound Campaign OS tools. Omit
the flag when the same key is intentionally authorized for the broader
Signaliz product toolset.

The server uses `https://api.signaliz.com/functions/v1` by default. Override it
with `SIGNALIZ_API_URL`.

Completed `find_email` and `verify_email` results expose only `email`, `status`,
`success`, `is_valid`, and `credits_used`. Processing and batch responses retain
the identifiers and paging fields required to resume them.

The four row-oriented tools scale with bounded recovery contracts:

- `find_email` accepts an HTTPS LinkedIn person profile URL (`/in/<slug>`) alone or a person name with
  `company_domain`. Its `contacts[]` batch rows use the same identity rule;
  re-call it with the returned `job_id`.
- `verify_email` accepts `emails[]`; re-call it with the returned `job_id`.
- `company_signal_enrichment` accepts 1-25 `companies[]` rows synchronously.
  Batches of 26-5,000 identity-only rows return a durable `job_id`; use
  `check_job_status` with `include_partial_results: true`, `page`, and
  `page_size` (maximum 25 for Company Signals) until `has_more` is false.
  Each row accepts a domain. Signaliz applies one fixed evidence policy.
  Pass completed output to `signal_to_copy` as `company_signal_result` to
  generate copy without repeating research, or reuse a synchronous row's
  `signal_run_id` after a recoverable upstream timeout.
  Signaliz automatically reuses compatible evidence inside the selected
  lookback and fills only uncovered gaps.
- `signal_to_copy` accepts 1-25 live `requests[]` with bounded concurrency.
  Batches of 26-5,000 rows create one durable job, complete missing signal
  research, and generate copy. Retrieve 100-row pages with `job_id` on
  `signal_to_copy` or with `check_job_status`. Uniform `enable_deep_search`
  controls apply to the full job; inline evidence remains a
  synchronous-only input. `lookback_days` is preserved at the batch or row
  level. Rows without qualifying evidence return `SIGNAL_DATA_REQUIRED`.
  Team and Agency include unlimited Signal to Copy; Free and Builder use 1
  credit per successful result.
- Retrieve completed Company/Copy pages within seven days. Cleaned pages return
  non-retryable `BATCH_RESULTS_EXPIRED`; agents must not automatically resubmit
  provider work and should require explicit review before creating a new job.
- `signals_everything` accepts one natural-language query, returns distinct
  companies with evidence, accepts optional `icp_context` for target-market
  qualification, and resumes asynchronously with
  `signal_search_run_id`. It supports up to 100 results under the strict
  sub-cent source-cost guardrail. Use it directly for net-new company
  discovery—do not source candidates yourself and then call
  `company_signal_enrichment`. A small preview can expand the same retained
  cohort by re-calling `signals_everything` with `signal_search_run_id` and a
  larger `limit`.
- `run_signaliz_flow` starts the full evidence-to-review workflow from a
  natural-language signal question and campaign offer. It returns a durable
  `run_id`; call `get_signaliz_flow` with that ID until the receipt is terminal.
  Flow carries company identity through people, verified email, and copy, but
  never sends outreach.
- Signal Awareness add, remove, update, schedule, pause/resume, run, list,
  export, and output tools all use the canonical monitor service. Every run
  invokes the same fixed Company Signal evidence engine; no caller-selectable
  signal types, model, prompt, provider, or lookback controls are exposed.

Run the transport smoke test with:

```bash
npm test
```