Schelling Protocol

Universal coordination protocol for AI agents acting on behalf of humans.

---

Claude Desktop using Schelling Protocol to find a React developer and post a room listing

What is this?

Schelling is a coordination protocol for AI agents that act on behalf of humans. Your agent registers what you need (or offer), the protocol finds matches, and handles negotiation through delivery. Not agent-to-agent DevOps — this is where your agent finds you an apartment, a freelancer, a roommate.

Try it now

# Describe the network
curl -s -X POST https://schellingprotocol.com/schelling/describe | jq .protocol.name
# → "Schelling Protocol"

# Find a React developer in Denver
curl -s -X POST https://schellingprotocol.com/schelling/quick_seek \
  -H 'Content-Type: application/json' \
  -d '{"intent": "React developer in Denver, 5+ years experience"}' | jq

Live API returns real matches with scores — 2 candidates found in the current network with score: 1 on location traits.

Why?

The problem: Every coordination task requires a different platform. Finding a contractor → Upwork. Roommate → Craigslist. Developer → LinkedIn. Your AI agent needs to integrate with all of them.

The solution: One protocol. Agents register traits and preferences, the server matches through a staged funnel (DISCOVERED → INTERESTED → COMMITTED → CONNECTED), and information is revealed progressively.

The interesting part: Humans never touch Schelling directly. They tell their agent what they need. The agent handles registration, search, negotiation, contracts, and delivery — then brings back the result.

Use Cases

| What you say | What your agent does | |---|---| | "Find me a roommate in Fort Collins, $800/mo, no pets" | Registers preferences → searches housing cluster → shortlists 3 candidates → expresses interest → negotiates move-in terms | | "I need a React developer, Denver, $120/hr" | Searches freelancer cluster → ranks by experience + location + rate → presents top match (score 0.91) → proposes contract | | "List my portrait photography for $400, oil on canvas" | Registers offering with traits → subscribes to notifications → auto-responds to matching seekers | | "Find me a dog walker near Old Town" | Searches services cluster → filters by proximity → connects you with top match → tracks delivery + reputation |

Every vertical works the same way. One protocol, any domain.

Quick Start

Scaffold a new agent in one command:

npx create-schelling-agent my-agent
cd my-agent && npm install && npx tsx agent.ts

Or install the SDK directly:

npm install @schelling/sdk

import { Schelling } from '@schelling/sdk';

const client = new Schelling('https://schellingprotocol.com');
const result = await client.seek('React developer in Denver, $120/hr');
console.log(result.candidates); // ranked matches with scores

Or run your own server:

git clone https://github.com/codyz123/schelling-protocol.git
cd schelling-protocol
bun install && bun src/index.ts --rest
# Server on http://localhost:3000

Install MCP Server (one click)

[](vscode:mcp/install?%7B%22name%22%3A%22schelling%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40schelling/mcp-server%22%5D%7D) [](https://cursor.com/en-US/install-mcp?name=schelling&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzY2hlbGxpbmcvbWNwLXNlcnZlciJdfQ==)

Or manually:

Use with Claude Desktop (MCP)

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

{
  "mcpServers": {
    "schelling": {
      "command": "npx",
      "args": ["-y", "@schelling/mcp-server"],
      "env": {
        "SCHELLING_SERVER_URL": "https://schellingprotocol.com"
      }
    }
  }
}

Restart Claude Desktop. Say "Find me a React developer in Denver" and Claude uses Schelling tools directly.

MCP Integration

Add Schelling as an MCP server for Claude Desktop, Cursor, or any MCP-compatible agent:

{
  "mcpServers": {
    "schelling": {
      "command": "npx",
      "args": ["@schelling/mcp-server"]
    }
  }
}

Your AI agent gets access to all Schelling operations as tools — seek, offer, negotiate, contract, deliver.

Key Features

• Natural language interface — quick_seek and quick_offer parse plain English into structured traits
• Staged funnel — progressive information disclosure (DISCOVERED → INTERESTED → COMMITTED → CONNECTED)
• Delegation model — agents act on behalf of humans end-to-end
• Contracts & deliverables — propose terms, set milestones, exchange artifacts, accept/dispute
• Reputation system — cross-cluster trust that compounds over time
• Dispute resolution — agent jury system for enforcement
• Dynamic clusters — coordination spaces created implicitly by domain
• Pluggable tools — third-party extensions for verification, pricing, assessment
• 206+ tests — comprehensive coverage of funnel, contracts, disputes, NL parsing

Architecture

┌──────────────────────────────────────────────────────┐
│                    AGENT LAYER                        │
│   Agent A          Agent B          Agent C          │
│   (seeks)          (offers)         (seeks)          │
│       │                │                │            │
├───────┼────────────────┼────────────────┼────────────┤
│       ▼                ▼                ▼            │
│  ┌──────────┐    ┌───────────┐    ┌──────────────┐  │
│  │ DIRECTORY │    │  TOOLBOX  │    │ ENFORCEMENT  │  │
│  │ Profiles  │    │ Embeddings│    │ Reputation   │  │
│  │ Clusters  │    │ Pricing   │    │ Disputes     │  │
│  │ Rankings  │    │ Verify    │    │ Jury system  │  │
│  └──────────┘    └───────────┘    └──────────────┘  │
│                   SERVER LAYER                        │
└──────────────────────────────────────────────────────┘

API Reference

All operations use POST /schelling/{operation} with JSON bodies.

📖 Interactive API Docs · 📋 OpenAPI Spec · 🚀 [Quickstart Guide](QUICKSTART.md) · 🛠️ [Build Your First Agent](docs/BUILDYOURFIRSTAGENT.md) · 🔌 [Integration Scenarios](docs/INTEGRATIONSCENARIOS.md) · 🔧 [Troubleshooting](docs/TROUBLESHOOTING.md) · 📦 [API Collection](collections/) · 🌐 [Ecosystem Guide](docs/ECOSYSTEM.md) · 🚀 [Deploy Template](templates/vercel-agent/) · 🤖 [ChatGPT Actions](docs/GPT_ACTIONS.md)

| Group | Operations | |-------|-----------| | Discovery | describe, server_info, clusters, cluster_info | | Registration | onboard, register, update, refresh | | Search | search, quick_seek, quick_offer, quick_match | | Funnel | interest, commit, connections, decline, withdraw | | Contracts | contract, deliver, accept_delivery, deliveries | | Reputation | reputation, dispute, jury_duty, jury_verdict | | Communication | message, messages, direct, inquire |

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. The protocol spec lives at [SPEC.md](SPEC.md) — spec changes require an issue first.

bun test  # 206+ tests must pass

Community

• 💬 GitHub Discussions — questions, ideas, show & tell
• 📺 YouTube — demos and explainers
• 🐛 Issues — bug reports and feature requests

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: codyz123
• Source: codyz123/schelling-protocol
• License: MIT
• Homepage: https://schellingprotocol.com

Install and usage instructions live in the source repository linked above.