Subconscious AI MCP

Chạy các thí nghiệm liên hợp và nghiên cứu nhân quả thông qua mô phỏng hành vi được hỗ trợ bởi AI

Tài liệu

Subconscious AI MCP Server

Run AI-powered conjoint experiments from Claude, Cursor, or any MCP-compatible client. Understand why people make decisions using causal inference and synthetic populations.

✨ Features

🧠 Causal Research - Validate research questions and generate statistically valid experiments
👥 Synthetic Populations - AI personas based on US Census microdata (IPUMS) for representative sampling
📊 Conjoint Analysis - AMCE (Average Marginal Component Effects) for measuring attribute importance
🤖 MCP Protocol - Works with Claude Desktop, Cursor, and any MCP-compatible AI assistant
🌐 REST API - Direct HTTP access for integrations (n8n, Zapier, custom apps)
🔌 Local stdio transport - Protocol-tested MCP connection for desktop clients

🚀 Quick Start

Supported: Run locally over stdio

Prerequisites:

Python 3.11+
A Subconscious AI account and Access token

# Clone the repository
git clone https://github.com/Subconscious-ai/ghostshell.git
cd ghostshell

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Set environment variables
export AUTH0_JWT_TOKEN="your_token_here"
export API_BASE_URL="https://api.subconscious.ai"

Add to your MCP config:

{
  "mcpServers": {
    "subconscious-ai": {
      "command": "/absolute/path/to/venv/bin/python3",
      "args": ["/absolute/path/to/server/main.py"],
      "env": {
        "AUTH0_JWT_TOKEN": "your_token",
        "API_BASE_URL": "https://api.subconscious.ai"
      }
    }
  }
}

Use an absolute path for both the Python executable and server/main.py. Keep the configuration file private because it contains a bearer credential. The checked examples under examples/ use the same supported stdio contract.

You can verify the protocol connection without calling a paid tool:

python scripts/smoke_stdio_mcp.py

The smoke test performs a real MCP initialize and tools/list exchange and expects all 15 registered tools.

Experimental: Hosted SSE

The hosted SSE endpoint is not a supported client setup yet. It accepts bearer credentials only through the Authorization header; URL query credentials are rejected. Because the hosted protocol/auth flow does not yet have a credentialed smoke test, do not rely on it for production client configuration.

📋 Available Tools

Tool	Description
`check_causality`	Validate that a research question is causal
`generate_attributes_levels`	Generate experiment attributes and levels using AI
`validate_population`	Validate target population demographics
`get_population_stats`	Get population statistics for a country
`create_experiment`	Create and run a conjoint experiment
`get_experiment_status`	Check experiment progress
`list_experiments`	List all your experiments
`get_experiment_results`	Get detailed experiment results
`get_run_details`	Get detailed run information
`get_run_artifacts`	Get run artifacts and files
`update_run_config`	Update run configuration
`generate_personas`	Generate AI personas for an experiment
`get_experiment_personas`	Get personas for an experiment
`get_amce_data`	Get AMCE analytics data
`get_causal_insights`	Get AI-generated causal insights

The checked mcp-tools.public.json file is the machine-readable discovery contract. It is generated directly from the same 15-tool registry used by the hosted API and includes deterministic source, transport, authentication, and schema metadata without credential values.

The manifest names the exact commit that owns every tool implementation. A squash merge creates a new owning commit even when the exported tools do not change, so regenerate and commit the manifest after the merge. A green pull-request artifact proves its named branch revision, not the default branch.

🔬 Example Workflow

You: "Check if this is a causal question: What factors influence people's decision to buy electric vehicles?"

AI: ✅ This is a causal question. Let me generate attributes for this study.

You: "Generate attributes for an EV preference study"

AI: Generated 5 attributes with 4 levels each:
    - Price: $25,000 / $35,000 / $45,000 / $55,000
    - Range: 200 miles / 300 miles / 400 miles / 500 miles
    ...

You: "Create an experiment about EV purchasing decisions"

AI: 🚀 Experiment created! Run ID: abc-123-xyz
    Status: Processing (surveying 500 synthetic respondents)

You: "Check the status of experiment abc-123-xyz"

AI: ✅ Experiment completed!
    - 500 respondents surveyed
    - Ready for analysis

You: "Get causal insights from this experiment"

AI: 📊 Key Findings:
    - Price has the strongest effect (-0.32 AMCE)
    - 400+ mile range increases preference by 28%
    - Brand reputation matters more than charging speed

🌐 REST API

Call tools directly via HTTP for integrations:

# List experiments
curl -X POST https://ghostshell-runi.vercel.app/api/call/list_experiments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

# Check causality
curl -X POST https://ghostshell-runi.vercel.app/api/call/check_causality \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"why_prompt": "What factors influence EV purchases?"}'

# Create experiment
curl -X POST https://ghostshell-runi.vercel.app/api/call/create_experiment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"why_prompt": "What factors influence EV purchases?", "confidence_level": "Reasonable"}'

# Get experiment results
curl -X POST https://ghostshell-runi.vercel.app/api/call/get_experiment_results \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"run_id": "your-run-id"}'

📡 API Endpoints

Endpoint	Method	Auth	Description
`/`	GET	No	Server info and available tools
`/api/health`	GET	No	Health check
`/api/tools`	GET	No	List all tools with schemas
`/api/sse`	GET	Yes	Experimental MCP SSE connection (Authorization header only)
`/api/call/{tool}`	POST	Yes	Call a tool directly

🏗️ Self-Hosting on Vercel

Deploy your own instance for your organization:

# Install Vercel CLI
npm i -g vercel

# Clone and deploy
git clone https://github.com/Subconscious-ai/ghostshell.git
cd ghostshell
vercel --prod

Configure environment variables in Vercel dashboard:

API_BASE_URL: https://api.subconscious.ai (or your backend URL)

⚠️ Users must provide their own tokens - the server proxies requests to the Subconscious AI backend.

💡 Feature Requests & Support

Have a feature request or need help? Email us at nihar@subconscious.ai

📚 Resources

Subconscious AI Platform - Create experiments via UI
API Documentation — Full API reference
MCP Protocol - Model Context Protocol specification
Conjoint Analysis - Learn about the methodology

📄 License

This software requires an active Subconscious AI subscription. See the LICENSE file for details.

Made with ❤️ by Subconscious AI