Which integrations are available for this server?

Uses Auth0 JWT tokens for authentication when making requests to the Subconscious AI backend API. Provides REST API endpoints for calling tools directly via HTTP, enabling integration with n8n workflows for AI-powered conjoint experiments and causal research. Supports self-hosting deployment on Vercel platform, with a hosted instance available at ghostshell-runi.vercel.app for MCP SSE connections. Provides REST API endpoints for calling tools directly via HTTP, enabling integration with Zapier workflows for AI-powered conjoint experiments and causal research.

How do I use mcp-subconscios?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-subconscios check if 'does social media affect mental health?' is a causal question" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Subconscious AI MCP Server

License: Proprietary Python 3.11+ MCP Protocol

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)
⚡ Real-time Updates - Server-Sent Events (SSE) for live experiment progress

🚀 Quick Start

Option 1: Use Hosted Server (Recommended)

No setup required! Add to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "subconscious-ai": {
      "url": "https://ghostshell-runi.vercel.app/api/sse?token=YOUR_TOKEN"
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "subconscious-ai": {
      "url": "https://ghostshell-runi.vercel.app/api/sse?token=YOUR_TOKEN"
    }
  }
}

🔑 Get your token at app.subconscious.ai → Settings → Access Token

Option 2: Run Locally

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"
      }
    }
  }
}

📋 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

🔬 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	MCP SSE connection (Authorization header preferred; query token fallback)
`/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.

mcp-subconscios