Agent Integration Guide

Integrate the SimpleFunctions thesis engine into your agent workflow. Three options: MCP server, CLI, or REST API.

MCP Server (Recommended)

Connect any MCP-compatible client — Claude Code, Cursor, Cline, Roo Code.

# Claude Code
claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp

# Cursor / Cline — add to MCP config:
{
  "mcpServers": {
    "simplefunctions": {
      "url": "https://simplefunctions.dev/api/mcp/mcp"
    }
  }
}

15 tools available:

CLI Integration

Every CLI command supports --json for machine-readable output.

npm install -g @spfunctions/cli
export SF_API_KEY=sf_live_xxx

The agent loop

Your agent only needs three operations:

# 1. Read — get current thesis state
sf context <thesisId> --json

# 2. Write — inject observations
sf signal <thesisId> "breaking: Hormuz blockade confirmed" --type news

# 3. React — trigger analysis when something big happens
sf evaluate <thesisId>

The heartbeat engine handles news scanning, price monitoring, and routine evaluation automatically every 15 minutes. Your agent doesn't need to poll for prices or search for news.

Efficient polling with delta API

Instead of fetching full context every cycle, use the lightweight changes endpoint:

sf context <thesisId> --json   # full state: ~5KB

# vs.

curl "https://simplefunctions.dev/api/thesis/<id>/changes?since=<ISO timestamp>" \
  -H "Authorization: Bearer sf_live_xxx"

# Nothing changed: {"changed": false} — 50 bytes
# Something changed: {"changed": true, "confidence": 0.89, "confidenceDelta": 0.02, ...} — 400 bytes

What-if scenarios

Zero LLM cost — pure computation:

# What if war stops and oil drops?
sf whatif <thesisId> --set "n1=0.1" --set "n3=0.2" --json

Returns adjusted edges and confidence without calling any LLM.

Plain text agent mode

For pipe-based agents, use --plain to skip the TUI:

echo "analyze my top edges" | sf agent <thesisId> --plain

REST API

Base URL: https://simplefunctions.dev

All requests need Authorization: Bearer sf_live_xxx.

Core endpoints

Create thesis example

curl -X POST https://simplefunctions.dev/api/thesis/create?sync=true \
  -H "Authorization: Bearer sf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"rawThesis": "US-Iran war pushes oil above $100 for 6 months"}'

Returns causal tree, edges with live prices, and confidence score.

Inject signal example

curl -X POST https://simplefunctions.dev/api/thesis/<id>/signal \
  -H "Authorization: Bearer sf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type": "news", "content": "Iran mines Strait of Hormuz", "source": "reuters"}'

Signal types: news, price_move, user_note, external, upcoming_event.

Webhook Integration

Configure a webhook URL when creating a thesis:

{"rawThesis": "...", "webhookUrl": "https://your-server.com/hook"}

The engine POSTs events when confidence changes ≥ 5% or positions need attention.

Best Practices

Writing theses:

• Be specific and directional: "Oil stays above $100 for 6 months" not "Oil prices"
• Include timeframe: helps the engine find relevant contracts
• One thesis = one view: don't mix unrelated predictions

Agent integration:

• Use /changes endpoint for polling — 100x cheaper than full context
• Inject signals immediately — don't batch them
• Let the heartbeat do routine monitoring — only call evaluate for breaking events
• Use what_if for scenario analysis before making trade decisions

Signal injection:

• type: "news" for external events
• type: "user_note" for your agent's analysis
• Include source attribution: "source": "my-agent"