io.github.SocioLogicAI/signal-relay
Connect AI agents to SocioLogic's synthetic persona platform for market research.
Open source Repository Open in the app JSON README (API)
About
Connect AI agents to SocioLogic's synthetic persona platform for market research.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- sociologicai
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 2.0.0
- Last push
- 2026-05-17T20:51:25Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:15
- Updated
- 2026-08-29 03:02:15
- Origin id
io.github.SocioLogicAI/signal-relay
README
# Signal Relay - SocioLogic MCP Server
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
A remote MCP (Model Context Protocol) server that connects AI agents to [SocioLogic's](https://sociologic.ai) synthetic persona platform. Interview realistic customer personas, run multi-persona research campaigns, and export board-ready reports—all through natural conversation.
## Features
- **24 MCP Tools** - Personas, campaigns, focus groups, web research, RNG, credits, and payments
- **High-Fidelity Personas** - Synthetic personas with consistent demographics, psychographics, and behavior
- **Semantic Memory** - RAG-powered memory retrieval for persona continuity across conversations
- **Edge Deployed** - Runs on Cloudflare Workers (300+ locations, <50ms latency)
- **Secure** - API key authentication, request validation, no data stored on edge
## Quick Start
### Use the Hosted Server (Recommended)
The fastest way to get started is using our hosted server at `https://mcp.sociologic.ai`.
1. **Get an API key** at [sociologic.ai/dashboard/api-keys](https://sociologic.ai/dashboard/api-keys) (100 free credits on signup)
2. **Configure your MCP client:**
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"sociologic": {
"transport": "http",
"url": "https://mcp.sociologic.ai",
"headers": {
"X-API-Key": "YOUR_API_KEY"
}
}
}
}
```
**Claude Code** (`.mcp.json` in your project):
```json
{
"mcpServers": {
"sociologic": {
"transport": "http",
"url": "https://mcp.sociologic.ai",
"headers": {
"X-API-Key": "YOUR_API_KEY"
}
}
}
}
```
3. **Start chatting!** Ask Claude to interview personas, create campaigns, or explore the marketplace.
## Self-Hosting
Deploy your own instance to Cloudflare Workers:
### Prerequisites
- [Node.js](https://nodejs.org/) v18+
- [Cloudflare account](https://dash.cloudflare.com/sign-up) (free tier works)
### Installation
```bash
# Clone the repository
git clone https://github.com/SocioLogicAI/signal-relay.git
cd signal-relay
# Install dependencies
npm install
# Login to Cloudflare
npx wrangler login
# Deploy
npx wrangler deploy
```
Your server will be available at `https://sociologic-mcp-server.<your-subdomain>.workers.dev`
### Local Development
```bash
npm run dev
```
Starts a local server at `http://localhost:8787`.
## Available Tools
| Tool | Description |
|------|-------------|
| `sociologic_list_personas` | List synthetic personas from marketplace or private collection |
| `sociologic_get_persona` | Get detailed persona information (demographics, psychographics, traits) |
| `sociologic_create_persona` | Generate a new persona from natural language description |
| `sociologic_get_persona_memories` | Retrieve persona's semantic memories via vector search |
| `sociologic_list_campaigns` | List research campaigns with status and results |
| `sociologic_get_campaign` | Get campaign details including interviews and findings |
| `sociologic_create_campaign` | Create multi-persona research campaign with custom questions |
| `sociologic_execute_campaign` | Execute draft campaign (async background processing) |
| `sociologic_export_campaign` | Export campaign results as PDF or JSON |
| `sociologic_list_focus_groups` | List focus groups for cohort-based research |
| `sociologic_get_focus_group` | Get focus group details with member personas |
| `sociologic_create_focus_group` | Create new focus group to organize personas |
| `sociologic_add_personas_to_focus_group` | Add personas to an existing focus group |
| `sociologic_get_credits_balance` | Check current credits balance and usage |
| `sociologic_search_web` | Search the web and scrape results |
| `sociologic_research_topic` | Research a topic with multiple sources |
## API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | POST | JSON-RPC 2.0 endpoint for MCP protocol |
| `/health` | GET | Health check (requires API key) |
| `/info` | GET | Server information and available tools |
## Example Usage
### List Available Personas
```bash
curl -X POST https://mcp.sociologic.ai/ \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "sociologic_list_personas",
"arguments": {
"visibility": "public",
"per_page": 10
}
}
}'
```
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SOCIOLOGIC_API_URL` | Backend API URL | `https://www.sociologic.ai` |
### wrangler.toml
```toml
[vars]
SOCIOLOGIC_API_URL = "https://www.sociologic.ai"
```
## Security
- **API keys** are passed via `X-API-Key` header or `Authorization: Bearer` header
- **Request size** limited to 1MB to prevent DoS
- **Input validation** via Zod schemas on all tool parameters
- **No data stored** on edge - all data flows through to the SocioLogic API
### Rate Limiting
For production deployments, we recommend enabling Cloudflare's rate limiting:
1. Go to Cloudflare Dashboard > Security > WAF > Rate limiting rules
2. Create a rule: 100 requests per 10 seconds per IP
## Architecture
```
┌─────────────────┐ ┌─────────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ MCP Client │─────▶│ Cloudflare Worker │─────▶│ SocioLogic API │
│ (Claude, etc) │ │ (This Server) │ │ │
│ │◀─────│ │◀─────│ │
└─────────────────┘ └─────────────────────┘ └─────────────────┘
│ │ │
│ MCP Protocol │ REST API │
│ (JSON-RPC 2.0) │ (HTTPS) │
└─────────────────────────┴──────────────────────────┘
```
## Pricing
| Operation | Credits |
|-----------|---------|
| List personas | 1 |
| Get persona | 1 |
| Create persona | 5-50 (by fidelity tier) |
| Interview persona | 1 per message |
| Campaign execution | Varies by size |
**Free tier:** 100 credits on signup. See [sociologic.ai/pricing](https://sociologic.ai/pricing) for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [SocioLogic Website](https://sociologic.ai)
- [API Documentation](https://sociologic.ai/docs)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)