synpop-mcp

MCP server for SynPop — simulate how US population segments respond to any statement or stimulus.

Add population intelligence to your Claude agent in 60 seconds.

What it does

SynPop conditions large language models on real US demographic survey data to simulate how different population segments respond to statements, messages, and policy questions. Results are validated against CFPB NFWBS 2016 survey data with a system-level Jensen-Shannon Divergence of 0.025.

Quick start

1. Get an API key

Sign up at synpop.logosnova.com and create an API key in Settings.

2. Add to your Claude config

{
  "mcpServers": {
    "synpop": {
      "command": "npx",
      "args": ["synpop-mcp"],
      "env": {
        "SYNPOP_API_KEY": "sp_live_your_key_here"
      }
    }
  }
}

3. Start querying

Your agent now has access to four tools. Ask Claude:

"How would Mid-Career Working Class and Retiree Comfortable respond to the message: I am just getting by financially?"

Tools

| Tool | Description | |------|-------------| | simulate_population | Simulate segment responses to a statement | | test_stimulus_variants | Compare multiple message framings | | get_segments | List all 12 available segments | | get_segment_profile | Get detailed profile for a segment |

Example response

{
  "study_id": "8a6f0b65-1c72-4587-be48-9751c9a31588",
  "stimulus": "I am just getting by financially.",
  "results": [
    {
      "segment": "young-urban-striving",
      "distribution": {
        "strongly_agree": 0.06,
        "agree": 0.18,
        "neutral": 0.21,
        "disagree": 0.38,
        "strongly_disagree": 0.17
      },
      "reasoning": "This segment self-identifies as financially competent 
        and resists 'just getting by' framing. SHED 2024 shows 76% describe 
        themselves as doing okay or better. However, 28% have less than one 
        month of liquid savings and 42% carry revolving balances, pulling 
        agreement higher.",
      "confidence": "high",
      "cached": false,
      "metadata": {
        "profile_version": 3,
        "conditioning_dimensions": [
          "age", "income", "education", 
          "geography", "political_orientation"
        ],
        "economic_context_period": "Q1 2026",
        "validated_domain": "consumer_financial_behavior",
        "benchmark_accuracy": {
          "system_result": "PASS",
          "spearman_median": 0.85,
          "jsd_average": 0.025,
          "passing_segments": 8,
          "total_segments": 12
        },
        "confidence": "high",
        "query_within_validated_domain": true
      }
    }
  ],
  "credits_used": 2,
  "credits_remaining": 498
}

Available segments

| Slug | Name | Age | Income | |------|------|-----|--------| | young-urban-striving | Young Urban Striving | 25-35 | $75K-$150K | | young-urban-struggling | Young Urban Struggling | 25-35 | <$40K | | young-rural | Young Rural | 25-35 | <$40K | | mid-career-suburban-professional | Mid-Career Suburban Professional | 36-50 | $75K-$150K | | mid-career-working-class | Mid-Career Working Class | 36-55 | $40K-$75K | | mid-career-rural | Mid-Career Rural | 36-50 | $40K-$75K | | high-income-established | High-Income Established | 36-60 | $150K+ | | pre-retirement-middle-income | Pre-Retirement Middle Income | 51-65 | $75K-$150K | | pre-retirement-constrained | Pre-Retirement Constrained | 51-65 | <$40K | | retiree-comfortable | Retiree Comfortable | 65+ | $75K+ | | retiree-constrained | Retiree Constrained | 65+ | <$40K | | high-income-urban-knowledge-worker | High-Income Urban Knowledge Worker | 36-50 | $150K+ |

Pricing

Credits are consumed per simulation. Get more credits at synpop.logosnova.com/settings/api.

| Package | Credits | Price | |---------|---------|-------| | Starter | 100 | $9 | | Standard | 500 | $39 | | Pro | 2,000 | $129 |

get_segments and get_segment_profile are free and do not consume credits.

Validation

SynPop's Direct Distribution (DD) architecture is benchmarked against CFPB National Financial Well-Being Survey 2016 data (6,394 respondents). System result: PASS. Overall Jensen-Shannon Divergence: 0.025. Spearman correlation median: 0.85.

Links

• Documentation
• Sign up
• API reference

License

MIT