SaaSFunnels MCP Server

Connect MCP-capable coding agents to safe SaaSFunnels setup context, diagnostics, readiness, and payload validation.

The SaaSFunnels MCP server is the agent-native path. Use hosted MCP for interactive clients and local stdio MCP for coding agents, CI, and other noninteractive workflows.

Hosted MCP exposes read, explain, validate, simulate, plan, and prepare capabilities only. Local MCP is read-only by default and exposes narrowly bounded write tools only when you explicitly enable them.

Connect hosted MCP with Clerk

During private testing, connect to the controlled current-host resource:

https://app.prevenue.ai/mcp

Choose Sign in, complete Clerk consent, and select the Clerk Organization linked to the workspace. The client does not need a copied SaaSFunnels API key. The public resource becomes https://app.saasfunnels.ai/mcp only after final-host certification.

Current Codex CLI configuration:

codex mcp add saasfunnels --url https://app.prevenue.ai/mcp --oauth-client-registration cimd
codex mcp login saasfunnels --scopes openid,profile,user:org:read

Use a reviewed pre-registered client or Client ID Metadata Document where the client supports it. Dynamic Client Registration is disabled by default. Cursor, VS Code/Copilot, and Claude Code should be configured with the same MCP URL and OAuth sign-in flow; exact client UI and current versions are certified before release, so do not treat an untested client as supported.

Start local stdio MCP

Start MCP over stdio:

SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY> saasfunnels mcp serve

Most MCP clients accept a command, arguments, and environment variables. Use this equivalent configuration:

{
  "mcpServers": {
    "saasfunnels": {
      "command": "saasfunnels",
      "args": ["mcp", "serve"],
      "env": {
        "SAASFUNNELS_API_KEY": "<DEVELOPER_READ_KEY>"
      }
    }
  }
}

Keep the secret in the client's secret store or environment facility rather than committing this example with a real value.

Enable the setup smoke write

To enable the setup smoke event tool, start the server explicitly with both a flag and an ingest key:

SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY> \
SAASFUNNELS_INGEST_API_KEY=<SAASFUNNELS_INGEST_KEY> \
saasfunnels mcp serve --enable-send-test-event

You can also set SAASFUNNELS_MCP_ENABLE_SEND_TEST_EVENT=true, but keep the tool disabled unless the agent is actively verifying setup.

For an explicitly authorized local Funnel-authoring session:

SAASFUNNELS_API_KEY=<DEVELOPER_READ_AND_FUNNELS_AUTHOR_KEY> \
saasfunnels mcp serve --enable-funnel-writes

This mode may update a versioned draft and submit source-free installation evidence. It cannot publish a Funnel.

MCP resources

The server exposes static, bounded resources:

Resource	Use it for
`saasfunnels://semantics/events`	Semantic event types, event kinds, sentiment fields, and signal-family unlock context.
`saasfunnels://sources/direct-api`	Direct API requirements and backend-only guidance.
`saasfunnels://sources/posthog`	PostHog webhook requirements and sample payload shape.
`saasfunnels://sources/segment`	Segment payload requirements and sample payload shape.
`saasfunnels://safety/data-exposure`	Redaction, secret handling, payload safety, and read-only policy.
`saasfunnels://features/catalog-schema`	Feature catalog manifest and local-only discovery boundary.
`saasfunnels://funnels/entry-installation`	Funnel entry kinds, installation evidence, and draft-only authoring boundary.
`saasfunnels://agent-handoff/direct-api/{target}`	Generated Direct API handoff for Markdown, Codex, Claude Code, or Cursor.

Docs search and llms.txt remain app surfaces for broader documentation. Use MCP resources when the agent needs the compact setup contract.

MCP tools

Tool	Mode	Required auth
`validate_event_payload`	Local	None
`validate_feature_catalog_manifest`	Local	None
`generate_direct_api_handoff`	Local	None
`get_integration_health`	Live read	`developer:read`
`get_workspace_readiness`	Live read	`developer:read`
`list_mapping_gaps`	Live read	`developer:read`
`list_recent_signals`	Live read	`developer:read`
`get_signal_payload_preview`	Live read	`developer:read`
`inspect_funnel_entry`	Live read	`developer:read`
`propose_funnel_entry_installation`	Live plan	`developer:read`
`get_account_strategy`	Hosted read	Clerk OAuth and workspace membership
`simulate_account_funnel_fit`	Hosted read-only simulation	Clerk OAuth and workspace membership
`apply_funnel_entry`	Explicit local stdio draft write	`funnels:author` and write enablement
`submit_funnel_entry_evidence`	Explicit local stdio evidence write	`funnels:author` and write enablement
`send_test_event`	Explicit setup smoke write	`direct:write` or `events:write` and write enablement

Hosted MCP does not expose any of the write rows. Local Funnel writes require --enable-funnel-writes, the current draft revision, idempotency, and existing audit controls; they can never publish. Tool results are compact and redacted rather than full data exports.

The two Account tools are hosted-only. get_account_strategy reads an existing reviewable brief and never starts a new analysis. simulate_account_funnel_fit evaluates at most eight current published Funnels against authoritative workspace facts, fails closed when those facts are unavailable, and never creates an enrollment, delivery, identity change, or runtime decision row.

Agent workflow examples

Ask an MCP-connected coding agent:

Use SaaSFunnels MCP to read the Direct API source requirements, inspect this codebase for durable backend events, and propose 3 to 6 account-scoped events. Do not put ingest keys in browser code.

Validate this candidate Direct API payload with SaaSFunnels MCP. If it fails, explain only the missing identity, unsafe fields, idempotency gap, and semantic mapping fix.

Check SaaSFunnels readiness and mapping gaps. Then tell me which source or event family I should fix first before routing signals.

Read this account's existing strategy and simulate its fit against current published Funnels. Explain the strongest evidence, suppression, uncertainty, and next owning action. Do not create CRM records or execute an outreach action.

Keep humans in the loop for writes. MCP can help agents find, validate, and diagnose setup, but SaaSFunnels is not a campaign execution engine or CRM task owner.