Social MCP Server

The first social network of the AI era. Connect with others through your AI assistant using the Model Context Protocol.

---

What is Social MCP?

Social MCP enables your AI assistant (Claude, ChatGPT, Gemini) to network on your behalf. Instead of scrolling feeds and sending connection requests, you tell your AI what you're looking for, and it finds compatible matches, facilitates introductions, and handles messaging—all through natural conversation.

Key Principles

• 🤖 AI-Native — Designed for AI assistants, not humans clicking buttons
• 🔒 Privacy-First — Your profile is only shared with mutual matches
• ✋ Double Opt-In — Both parties must accept before any introduction
• 🌐 Platform Agnostic — Works with any MCP-compatible AI client

---

Features

Feature	Description
Profile Management	Register and update your display name, bio, and location
Intent-Based Matching	Describe what you're looking for in natural language
AI-Powered Matching	Semantic matching finds complementary intents
Double Opt-In Connections	Both parties must accept before connecting
Secure Messaging	Send messages to matched connections
Real-Time Notifications	Get notified of new matches and messages via SSE
Session Persistence	Your identity persists across conversations

---

Quick Start (5 minutes)

For Claude Desktop

1. Download the MCP server from socialmcp.com

2. Extract and install dependencies:

   cd mcp-server
   npm install
   npm run build
   

3. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

   {
     "mcpServers": {
       "social-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-server/dist/index.js"],
         "env": {
           "SOCIAL_MCP_API_URL": "https://cwaozizmiipxstlwmepk.supabase.co/functions/v1"
         }
       }
     }
   }
   

4. Restart Claude Desktop and start chatting:

   "Register me on Social MCP as John Doe. I'm a startup founder looking for a technical co-founder."

---

Installation Methods

Method 1: Local STDIO Server (Recommended for Claude Desktop)

Best for: Claude Desktop users who want the simplest setup.

# Clone or download
git clone https://github.com/yourusername/social-mcp.git
cd social-mcp/mcp-server

# Install and build
npm install
npm run build

# The server runs automatically when Claude Desktop starts

Pros: Simple, no deployment needed, credentials stored locally
Cons: Only works with STDIO-based clients (Claude Desktop)

Method 2: Hosted HTTP Server (For Claude Web & Push Notifications)

Best for: Claude Web users, or anyone wanting real-time push notifications.

The HTTP server provides Server-Sent Events (SSE) for real-time notifications when you receive new matches or messages.

# Build and run locally
npm install
npm run build
npm run start:http

# Or deploy to a cloud provider (see Deployment section)

Then configure your MCP client to connect to the HTTP endpoint.

Method 3: Direct Edge Function Access

Best for: Developers building custom integrations.

You can call the edge function directly without using the MCP server:

curl -X POST https://cwaozizmiipxstlwmepk.supabase.co/functions/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"social_register","arguments":{"display_name":"John"}},"id":1}'

---

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "social-mcp": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "SOCIAL_MCP_API_URL": "https://cwaozizmiipxstlwmepk.supabase.co/functions/v1"
      }
    }
  }
}

Claude Web (via mcp-remote or Hosted Server)

For Claude Web, you need the HTTP server running somewhere accessible:

{
  "mcpServers": {
    "social-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-deployed-server.com/mcp"]
    }
  }
}

Environment Variables

Variable	Required	Default	Description
SOCIAL_MCP_API_URL	No	https://cwaozizmiipxstlwmepk.supabase.co/functions/v1	Backend API endpoint
SUPABASE_URL	For HTTP	—	Supabase project URL (for realtime)
SUPABASE_ANON_KEY	For HTTP	—	Supabase anonymous key (for realtime)
PORT	No	3000	HTTP server port

---

Available Tools

social_register

Register a new profile or update your existing profile.

Parameter	Type	Required	Description
display_name	string	Yes	Your display name
bio	string	No	A brief bio about yourself
location	string	No	Your location

Example:

User: "Register me on Social MCP as Sarah Chen. I'm a product designer based in San Francisco."

Response:

{
  "success": true,
  "profile_id": "uuid-here",
  "api_key": "smcp_xxxxx",
  "message": "Welcome to Social MCP, Sarah Chen!"
}

---

social_login

Log in to an existing profile using your API key.

Parameter	Type	Required	Description
api_key	string	Yes	Your API key from registration

Example:

User: "Log me into Social MCP with my API key smcp_xxxxx"

---

social_whoami

Check your current logged-in profile.

Parameter	Type	Required	Description
—	—	—	No parameters required

Example:

User: "Who am I on Social MCP?"

---

social_set_intent

Set what kind of connections you're looking for. This is the core of matching.

Parameter	Type	Required	Description
category	string	Yes	One of: professional, romance, friendship, expertise, sports, learning, other
description	string	Yes	Natural language description of what you're looking for
criteria	object	No	Additional structured criteria (key-value pairs)

Example:

User: "I'm looking for a technical co-founder for my AI startup. 
       They should have ML experience and be willing to work full-time."

AI uses:

{
  "category": "professional",
  "description": "Looking for a technical co-founder for AI startup with ML experience, willing to work full-time",
  "criteria": {
    "role": "technical co-founder",
    "skills": ["ML", "AI"],
    "commitment": "full-time"
  }
}

---

social_get_intents

Get all your active intents.

Parameter	Type	Required	Description
—	—	—	No parameters required

---

social_find_matches

Actively search for matches based on your current intents.

Parameter	Type	Required	Description
—	—	—	No parameters required

Returns: List of potential matches ranked by compatibility score.

---

social_get_matches

Get your current matches and their status.

Parameter	Type	Required	Description
—	—	—	No parameters required

Match Statuses:

• pending_a — Fresh match, awaiting first response from profile A
• pending_b — Profile A accepted, awaiting response from profile B
• accepted — Both parties accepted, connection established!
• rejected — One party declined
• expired — Match expired (7 days without response)

---

social_respond_match

Accept or reject a potential match.

Parameter	Type	Required	Description
match_id	string	Yes	The match UUID
action	string	Yes	Either accept or reject

Example:

User: "Accept the match with Sarah Chen"

---

social_send_message

Send a message to a connected match.

Parameter	Type	Required	Description
match_id	string	Yes	The match UUID
content	string	Yes	Your message content

Example:

User: "Send a message to Sarah: 'Hi! I'd love to chat about your startup idea.'"

---

social_get_messages

Get the message history with a match.

Parameter	Type	Required	Description
match_id	string	Yes	The match UUID

---

social_get_notifications

Check for new notifications (matches, messages, etc.).

Parameter	Type	Required	Description
—	—	—	No parameters required

Returns: Summary of pending matches, connection requests, active connections, and unread messages.

---

Complete Workflow Example

Here's a complete conversation showing the Social MCP flow:

1. Registration

You: "I want to use Social MCP. Register me as Alex Rivera, a software engineer in Austin interested in finding co-founders."

Claude: I'll register you on Social MCP.

✅ Welcome to Social MCP, Alex Rivera!

Your profile is now active. I've saved your API key securely. Now let's set what you're looking for...

2. Setting Intent

You: "I'm looking for a business-minded co-founder for a developer tools startup. Someone with sales or marketing experience who understands developers."

Claude: I've set your intent:

📌 Intent Active: Professional networking

• Looking for: Business co-founder with sales/marketing experience
• For: Developer tools startup

I'll monitor for compatible matches!

3. Checking Matches

You: "Do I have any matches yet?"

Claude: Let me check your matches...

🎉 2 New Potential Matches:

1. Jordan Kim (87% match) "Former DevRel at Stripe, looking to join early-stage devtools startup as business co-founder"

2. Morgan Chen (72% match) "Marketing lead seeking technical co-founder for B2B SaaS"

Would you like to accept any of these?

4. Accepting a Match

You: "Accept the match with Jordan Kim"

Claude: ✅ Match accepted!

Jordan has been notified. Once they accept, you'll be connected and can start messaging.

5. Connection Established

You: "Check my notifications"

Claude: 🎉 Great news!

Jordan Kim accepted your connection! You're now connected.

Would you like me to send them a message to introduce yourself?

6. Messaging

You: "Yes, send them: 'Hi Jordan! I saw your DevRel background at Stripe - that's exactly the kind of experience I'm looking for. Would love to chat about the devtools space. Free for a call this week?'"

Claude: ✅ Message sent to Jordan Kim!

I'll let you know when they reply.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User's AI Client                        │
│                  (Claude Desktop / ChatGPT / etc.)              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ MCP Protocol (STDIO or HTTP)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Social MCP Server                          │
│  ┌─────────────────┐    ┌─────────────────┐                     │
│  │  STDIO Server   │    │   HTTP Server   │                     │
│  │  (index.ts)     │    │ (http-server.ts)│                     │
│  │                 │    │                 │                     │
│  │ • Tool handlers │    │ • SSE push      │                     │
│  │ • Credential    │    │ • Session mgmt  │                     │
│  │   storage       │    │ • Realtime sub  │                     │
│  └────────┬────────┘    └────────┬────────┘                     │
│           │                      │                               │
│           └──────────┬───────────┘                               │
│                      │                                           │
└──────────────────────┼───────────────────────────────────────────┘
                       │ HTTPS
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Backend Edge Function                         │
│                  (supabase/functions/mcp)                        │
│                                                                  │
│  • JSON-RPC request handling                                     │
│  • Profile & intent management                                   │
│  • Match creation & status updates                               │
│  • Message storage & retrieval                                   │
│  • Notification generation                                       │
└─────────────────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                      PostgreSQL Database                         │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐     │
│  │ profiles │  │ intents  │  │ matches  │  │ messages     │     │
│  ├──────────┤  ├──────────┤  ├──────────┤  ├──────────────┤     │
│  │ id       │  │ id       │  │ id       │  │ id           │     │
│  │ name     │◄─┤ profile  │◄─┤ profile_a│  │ match_id     │     │
│  │ bio      │  │ category │  │ profile_b│  │ sender_id    │     │
│  │ location │  │ desc     │  │ intent_a │  │ content      │     │
│  └──────────┘  │ criteria │  │ intent_b │  │ created_at   │     │
│                └──────────┘  │ score    │  └──────────────┘     │
│                              │ status   │                        │
│  ┌──────────────────┐        └──────────┘                        │
│  │ notifications    │                                            │
│  ├──────────────────┤        ┌──────────────┐                    │
│  │ id               │        │ mcp_api_keys │                    │
│  │ profile_id       │        ├──────────────┤                    │
│  │ type             │        │ key_hash     │                    │
│  │ payload          │        │ profile_id   │                    │
│  │ is_delivered     │        │ scopes       │                    │
│  └──────────────────┘        └──────────────┘                    │
└─────────────────────────────────────────────────────────────────┘

Database Schema

Table	Purpose
profiles	User profiles with display name, bio, location
intents	What users are looking for (category + description)
matches	Connections between two users with acceptance status
messages	Chat messages between matched users
notifications	Pending notifications for async delivery
mcp_api_keys	Hashed API keys for authentication
mcp_sessions	HTTP session management for stateful connections

---

Privacy & Security

Double Opt-In System

User A sets intent     User B sets intent
       │                      │
       └──────────┬───────────┘
                  ▼
           Matching Engine
           finds compatibility
                  │
                  ▼
    ┌─────────────────────────┐
    │ Match created (pending) │
    └─────────────────────────┘
                  │
       ┌──────────┴──────────┐
       ▼                     ▼
   User A sees           User B doesn't
   match, accepts        see anything yet
       │
       ▼
   User B NOW sees
   connection request
       │
       ▼
   User B accepts
       │
       ▼
   ✅ CONNECTED!
   Both can message

Data Protection

• Hashed API Keys — Keys are stored as SHA-256 hashes, never plaintext
• Minimal Data Sharing — Only display name and intent are shared with matches
• No Browsing — Users can't browse all profiles, only see their matches
• Expiring Matches — Unresponded matches expire after 7 days
• Row-Level Security — Database policies restrict data access

Authentication Methods

1. API Key — Generated at registration, stored locally by the STDIO server
2. Session ID — For HTTP server, persisted across requests
3. Profile ID — Fallback for legacy compatibility

---

Deployment

Railway (Recommended)

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Set environment variables in Railway dashboard:

• SUPABASE_URL
• SUPABASE_ANON_KEY

Fly.io

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Login and deploy
fly auth login
fly launch
fly deploy

Docker

# Build
docker build -t social-mcp-server .

# Run
docker run -p 3000:3000 \
  -e SUPABASE_URL=your-url \
  -e SUPABASE_ANON_KEY=your-key \
  social-mcp-server

Render

1. Create a new Web Service
2. Connect your repository
3. Set build command: npm install && npm run build
4. Set start command: npm run start:http
5. Add environment variables

---

Development

Prerequisites

• Node.js 18+
• npm or yarn

Local Setup

# Clone repository
git clone https://github.com/yourusername/social-mcp.git
cd social-mcp/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run STDIO server (for testing with Claude Desktop)
node dist/index.js

# Run HTTP server (for web clients)
npm run start:http

Project Structure

mcp-server/
├── src/
│   ├── index.ts        # STDIO server for Claude Desktop
│   └── http-server.ts  # HTTP server with SSE for web clients
├── dist/               # Compiled JavaScript
├── package.json
├── tsconfig.json
├── Dockerfile
├── fly.toml            # Fly.io configuration
├── README.md
└── DEPLOY.md           # Detailed deployment guide

Building from Source

npm run build

This compiles TypeScript from src/ to dist/.

---

Troubleshooting

"Tool not found" in Claude

Cause: MCP server not configured correctly.

Solution:

1. Check the path in claude_desktop_config.json is absolute and correct
2. Ensure npm run build completed successfully
3. Restart Claude Desktop completely

"Authentication failed"

Cause: Invalid or expired API key.

Solution:

1. Re-register to get a new API key
2. Or use social_login with your existing key

"No matches found"

Cause: No compatible intents in the system.

Solution:

1. Ensure your intent is set (social_set_intent)
2. Use social_find_matches to trigger a new search
3. Wait for more users to join!

HTTP server not receiving notifications

Cause: Supabase realtime not configured.

Solution:

1. Ensure SUPABASE_URL and SUPABASE_ANON_KEY are set
2. Check that realtime is enabled for notifications and messages tables

Credentials lost between sessions

Cause: Credentials file not persisted (containerized environments).

Solution:

1. For Docker: Mount a volume for ~/.social-mcp-credentials.json
2. Or use the HTTP server which uses database sessions

---

API Reference

Backend Endpoint

POST https://cwaozizmiipxstlwmepk.supabase.co/functions/v1/mcp

Request Format (JSON-RPC 2.0)

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "social_register",
    "arguments": {
      "display_name": "John Doe"
    }
  },
  "id": 1
}

Authentication Headers

Header	Description
x-mcp-api-key	Your API key (preferred)
x-mcp-profile-id	Profile UUID (fallback)
mcp-session-id	HTTP session ID

Response Format

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Success message here"
      }
    ]
  },
  "id": 1
}

---

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

---

License

MIT License — see LICENSE for details.

---

Links

• Website: www.social-mcp.org
• MCP Specification: modelcontextprotocol.io

---

<p align="center"> <strong>Built for the AI era. 🤖💬</strong> </p>