Skip to main content

Shared Context Server

CI Docker GHCR PyPI version PyPI - Python Version codecov Python 3.10+ License: MIT

Content Navigation

Symbol Meaning Time Investment
🚀 Quick start 2-5 minutes
⚙️ Configuration 10-15 minutes
🔧 Deep dive 30+ minutes
💡 Why this works Context only
⚠️ Important note Read carefully

🎯 Quick Understanding (30 seconds)

A shared workspace for AI agents to collaborate on complex tasks.

The Problem: AI agents work independently, duplicate research, and can't build on each other's discoveries.

The Solution: Shared sessions where agents see previous findings and build incrementally instead of starting over.

# Agent 1: Security analysis
session.add_message("security_agent", "Found SQL injection in user login")

# Agent 2: Performance review (sees security findings)
session.add_message("perf_agent", "Optimized query while fixing SQL injection")

# Agent 3: Documentation (has full context)
session.add_message("docs_agent", "Documented secure, optimized login implementation")

Each agent builds on previous work instead of starting over.

💡 Uses MCP Protocol: Model Context Protocol - the standard for AI agent communication (works with Claude Code, Gemini, VS Code, Cursor, and frameworks like CrewAI).


🚀 Try It Now (2 minutes)

⚠️ Important: Choose Your Deployment Method

Docker (Recommended for Multi-Client Collaboration):

  • ✅ Shared context across all MCP clients (Claude Code + Cursor + Windsurf)
  • ✅ Persistent service - single server instance on port 23456
  • ✅ True multi-agent collaboration - agents share sessions and memory
  • 🎯 Use when: You want multiple tools to collaborate on the same tasks

uvx (Quick Trial & Testing Only):

  • ⚠️ Isolated per-client - each MCP client gets its own separate instance
  • ⚠️ No shared context - Claude Code and Cursor can't see each other's work
  • ✅ Quick testing - perfect for trying features without Docker setup
  • 🎯 Use when: Quick feature testing or learning the MCP tools in isolation
# 🐳 Docker: Multi-client shared collaboration (RECOMMENDED)
# ⚠️ Requires environment variables - see Step 1 below

# 📦 uvx: Isolated single-client testing only
# ⚠️ Requires API key - see Step 1 below
uvx shared-context-server --help

💡 TL;DR: Use Docker for real multi-agent work, uvx for quick testing only.

Prerequisites Check (30 seconds)

Choose your path:

  • ✅ Docker (recommended): docker --version works
  • ✅ uvx Trial: uvx --version works (testing only)

Environment Configuration Templates

Choose your .env template (for local development):

# 🚀 Quick Start (recommended) - Essential variables only
cp .env.minimal .env

# 🔧 Full Development - All development features
cp .env.example .env

# 🐳 Docker Deployment - Container-optimized paths
cp .env.docker .env

💡 Most users want .env.minimal - it contains only the 12 essential variables you actually need.

Step 1: Generate Keys & Start Server

🚀 One-Command Setup (Recommended)

# Clone and generate everything automatically
git clone https://github.com/leoric-crown/shared-context-server.git
cd shared-context-server
python scripts/generate_keys.py --docker-only
# ↳ Generates keys, shows Docker commands, creates .env file

Option A: Docker Compose (Recommended)

# After running the key generator above, choose your deployment:

# 🚀 Production (pre-built image from GHCR):
make docker
# OR: docker compose up -d

# 🔧 Development (with hot reload):
make dev-docker
# OR: docker compose -f docker-compose.dev.yml up -d

# 🏗️ Production (build locally):
make docker-local
# OR: docker compose -f docker-compose.yml -f docker-compose.local.yml up -d

Alternative: Raw Docker Commands

# If you prefer docker run over docker compose:
docker run -d --name shared-context-server -p 23456:23456 \
  -e API_KEY="your-generated-api-key" \
  -e JWT_SECRET_KEY="your-generated-jwt-secret" \
  -e JWT_ENCRYPTION_KEY="your-generated-jwt-encryption-key" \
  ghcr.io/leoric-crown/shared-context-server:latest

Option B: uvx Trial (Isolated Testing Only)

# Generate keys first
python scripts/generate_keys.py --uvx --no-file
# ↳ Shows the exact uvx command with generated keys

# Example output command to run:
API_KEY="generated-key" JWT_SECRET_KEY="generated-secret" \
  uvx shared-context-server --transport http

# ⚠️ IMPORTANT: Each MCP client gets isolated instances
# No shared context between Claude Code, Cursor, Windsurf

Option C: Local Development

# Full development setup
git clone https://github.com/leoric-crown/shared-context-server.git
cd shared-context-server
uv sync
python scripts/generate_keys.py --local
# ↳ Creates .env file and shows make dev command

make dev  # Starts with hot reload

Step 2: Connect Your MCP Client

The key generation script shows the exact commands with your API key. Replace YOUR_API_KEY_HERE with your generated key:

# Claude Code (simple HTTP transport)
claude mcp add --transport http scs http://localhost:23456/mcp/ \
  --header "X-API-Key: YOUR_API_KEY_HERE"

# Gemini CLI
gemini mcp add scs http://localhost:23456/mcp -t http -H "X-API-Key: YOUR_API_KEY_HERE"

# Test connection
claude mcp list  # Should show: ✓ Connected

VS Code Configuration

Add to your existing .vscode/mcp.json (create if it doesn't exist):

{
  "servers": {
    "shared-context-server": {
      "type": "http",
      "url": "http://localhost:23456/mcp",
      "headers": {"X-API-Key": "YOUR_API_KEY_HERE"}
    }
  }
}

Cursor Configuration

Add to your existing .cursor/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "shared-context-server": {
      "command": "mcp-proxy",
      "args": ["--transport=streamablehttp", "http://localhost:23456/mcp/", "--headers", "X-API-Key", "YOUR_API_KEY_HERE"]
    }
  }
}

Claude Desktop Configuration

Add to your existing claude_desktop_config.json:

On MacOS, you may have to provide explicity path to mcp-proxy.

Have not tested in Windows.

{
    "scs": {
      "command": "/Users/YOUR_USER/.local/bin/mcp-proxy",
      "args": ["--transport=streamablehttp", "http://localhost:23456/mcp/", "--headers", "X-API-Key", "YOUR_API_KEY_HERE"]
    }
}

Step 3: Verify & Monitor

📝 Note: If you used make docker-prod, press Ctrl+C to exit the log viewer first, then run these commands in the same terminal.

# Test your setup (30 seconds)
# Method 1: Quick health check
curl http://localhost:23456/health

# Method 2: Create actual test session (see it in web UI!)
# If you have Claude Code with shared-context-server MCP tools:
# Run this in Claude: Create a session with purpose "README test setup"
# Expected: {"success": true, "session_id": "session_...", ...}

# Method 3: Test MCP tools discovery
npx @modelcontextprotocol/inspector --cli --method tools/list \
  -e API_KEY=$API_KEY \
  -e JWT_SECRET_KEY=$JWT_SECRET_KEY \
  -e JWT_ENCRYPTION_KEY=$JWT_ENCRYPTION_KEY \
  uv run python -m shared_context_server.scripts.cli

# Expected: {"tools": [...]} (proves MCP tools are available)

# Method 4: For Docker deployment, test via HTTP endpoint
npx @modelcontextprotocol/inspector --cli --method tools/list \
  http://localhost:23456/mcp
# View the dashboard
open http://localhost:23456/ui/  # Real-time session monitoring

✅ Success indicators:

  • Health endpoint returns {"status": "healthy", ...}
  • Dashboard loads at http://localhost:23456/ui/ and shows active sessions
  • MCP Inspector validation error (proves MCP protocol is working)
  • MCP client shows ✓ Connected status

📊 Web Dashboard (MVP)

Real-time monitoring interface for agent collaboration:

  • Live session overview with active agent counts
  • Real-time message streaming without page refreshes
  • Session isolation visualization to track multi-agent workflows
  • Performance monitoring for collaboration efficiency

💡 Perfect for: Monitoring agent handoffs, debugging collaboration flows, and demonstrating multi-agent coordination to stakeholders.

📦 PyPI Installation (Alternative Method)

The shared-context-server is also available on PyPI for quick testing:

# 📦 Install and try (creates isolated instances per client)
uvx shared-context-server --help
uvx shared-context-server --version

# ⚠️ For multi-client collaboration, use Docker instead

💡 When to use PyPI/uvx: Quick feature testing, learning MCP tools, single-client workflows only.


🔧 Choose Your Path

Are you...

├── 👨‍💻 Building a side project?
│   → [Simple Integration](#-simple-integration) (5 minutes)
│
├── 🏢 Planning enterprise deployment?
│   → [Enterprise Setup](#-enterprise-considerations) (15+ minutes)
│
├── 🎓 Researching multi-agent systems?
│   → [Technical Deep Dive](#-technical-architecture) (30+ minutes)
│
└── 🤔 Just evaluating the concept?
    → [Framework Integration Examples](#-framework-examples) (5 minutes)

🚀 Simple Integration

Works with existing tools you already use:

Direct MCP Integration (Tested)

# Via Claude Code or any MCP client
claude mcp add-json shared-context-server '{"command": "mcp-proxy", "args": ["--transport=streamablehttp", "http://localhost:23456/mcp/"]}'

# Direct MCP usage (use proper MCP client in production)
# Example shows concept - use mcp-proxy or MCP client libraries
import asyncio
from mcp_client import MCPClient  # Conceptual - use actual MCP client

async def create_session():
    client = MCPClient("http://localhost:23456/mcp/")
    return await client.call_tool("create_session", {"purpose": "agent collaboration"})

⚠️ Framework Integration Status: Direct MCP protocol tested. CrewAI, AutoGen, and LangChain integrations are conceptual - we welcome community contributions to develop and test these patterns.

➡️ Next: MCP Integration Examples


⚙️ Framework Examples

Code Review Pipeline

  1. Security Agent finds vulnerabilities → shares findings
  2. Performance Agent builds on security context → optimizes safely
  3. Documentation Agent documents complete solution

💡 Why this works: Each agent builds on discoveries instead of duplicating work.

Research & Implementation

  1. Research Agent gathers requirements → shares insights
  2. Architecture Agent designs using research → documents decisions
  3. Developer Agent implements with full context

More examples: Collaborative Workflows Guide

What works: ✅ MCP clients (Claude Code, Gemini, VS Code, Cursor) What's conceptual: 🔄 Framework patterns (CrewAI, AutoGen, LangChain) - community contributions welcome


🔧 What This Is / What This Isn't

✅ What this MCP server provides

  • Real-time collaboration substrate for multi-agent workflows
  • Session isolation with clean boundaries between different tasks
  • MCP protocol compliance that works with any MCP-compatible agent framework
  • Infrastructure layer that enhances existing orchestration tools

💡 Why MCP protocol? Universal compatibility - works with Claude Code, CrewAI, AutoGen, LangChain, and custom frameworks without vendor lock-in.

❌ What this MCP server isn't

  • Not a vector database - Use Pinecone, Milvus, or Chroma for long-term storage
  • Not an orchestration platform - Use CrewAI, AutoGen, or LangChain for task management
  • Not for permanent memory - Sessions are for active collaboration, not archival

💡 Why this approach? We enhance your existing tools rather than replacing them - no need to rewrite your agent workflows.


🏢 Enterprise Considerations

⚙️ Production Setup & Scaling

Development → Production Path

Development (SQLite)

  • ✅ Zero configuration
  • ✅ Perfect for prototyping
  • ❌ Limited to ~5 concurrent agents

Production (PostgreSQL)

  • ✅ High concurrency (20+ agents)
  • ✅ Enterprise backup/recovery
  • ❌ Requires database management

Enterprise Features Roadmap

  • SSO Integration: SAML/OIDC support planned
  • Audit Logging: Enhanced compliance logging
  • High Availability: Multi-node deployment
  • Advanced RBAC: Attribute-based permissions

Migration: Start with SQLite, migrate when you hit concurrency limits.

🔧 Security & Compliance

Current Security Features

  • JWT Authentication: Role-based access control
  • Input Sanitization: XSS and injection prevention
  • Secure Token Management: Prevents JWT exposure vulnerabilities
  • Message Visibility: Public/private/agent-only filtering

Enterprise Security Roadmap

  • SSO Integration: SAML, OIDC, Active Directory
  • Audit Trails: SOX, HIPAA-compliant logging
  • Data Governance: Retention policies, geographic residency
  • Advanced Encryption: At-rest and in-transit encryption

🔧 Technical Architecture

🔄 Deployment Architecture: Docker vs uvx

Docker Deployment (Multi-Client Shared Context)

┌─────────────────┐    ┌──────────────────────┐
│   Claude Code   │───▶│                      │
├─────────────────┤    │  Shared HTTP Server  │
│     Cursor      │───▶│   (port 23456)       │
├─────────────────┤    │                      │
│    Windsurf     │───▶│  • Single database   │
└─────────────────┘    │  • Shared sessions   │
                       │  • Cross-tool memory │
                       └──────────────────────┘

✅ Enables: True multi-agent collaboration, session sharing, persistent context

uvx Deployment (Isolated Per-Client)

┌─────────────────┐    ┌─────────────────┐
│   Claude Code   │───▶│ Isolated Server │
└─────────────────┘    │ + Database #1   │
                       └─────────────────┘
┌─────────────────┐    ┌─────────────────┐
│     Cursor      │───▶│ Isolated Server │
└─────────────────┘    │ + Database #2   │
                       └─────────────────┘
┌─────────────────┐    ┌─────────────────┐
│    Windsurf     │───▶│ Isolated Server │
└─────────────────┘    │ + Database #3   │
                       └─────────────────┘

⚠️ Limitation: No cross-tool collaboration, separate contexts, testing only

💡 Key Insight: Docker provides the "shared" in shared-context-server, while uvx creates isolated silos.

Core Design Principles

Session-Based Isolation

What: Each collaborative task gets its own workspace Why: Prevents cross-contamination while enabling rich collaboration within teams

Message Visibility Controls

What: Four-tier system (public/private/agent-only/admin-only) Why: Granular information sharing - agents can have private working memory and shared discoveries

MCP Protocol Integration

What: Model Context Protocol compliance for universal compatibility Why: Works with any MCP-compatible framework without custom integration code

Performance Characteristics

Designed for Real-Time Collaboration

  • <30ms message operations for smooth agent handoffs
  • 2-3ms fuzzy search across session history
  • 20+ concurrent agents per session
  • Session continuity during agent switches

💡 Why these targets? Sub-30ms ensures imperceptible delays during agent handoffs, maintaining workflow momentum.

Scalability Considerations

  • SQLite: Development and small teams (<5 concurrent agents)
  • PostgreSQL: Production deployments (20+ concurrent agents)
  • Connection pooling: Built-in performance optimization
  • Multi-level caching: >70% cache hit ratio for common operations
Database & Storage

Architecture Decision: Database Choice

SQLite for Development

  • ✅ Zero configuration
  • ✅ Perfect for prototyping
  • ❌ Single writer limitation

PostgreSQL for Production

  • ✅ Multi-writer concurrency
  • ✅ Enterprise backup/recovery
  • ✅ Advanced indexing and performance
  • ❌ Requires database administration

Database Backend

  • Unified: SQLAlchemy Core (supports SQLite, PostgreSQL, MySQL)
  • Development: SQLite with aiosqlite driver (fastest, simplest)
  • Production: PostgreSQL/MySQL with async drivers (scalable, robust)

Migration Path: SQLAlchemy backend provides smooth transition to PostgreSQL when scaling needs arise.

💡 Why this hybrid approach? Optimizes for developer experience during development while supporting enterprise scale in production.


📖 Documentation & Next Steps

🟢 Getting Started Paths

🟡 Production Deployment

🔴 Advanced Topics

All documentation: Documentation Index


🚀 Development Commands

make help        # Show all available commands
make dev         # Start development server with hot reload
make test        # Run tests with coverage
make quality     # Run all quality checks
make docker      # Production Docker (GHCR image) → shows logs
make dev-docker  # Development Docker (local build + hot reload) → shows logs
# ⚠️ Both commands show live logs - press Ctrl+C to exit and continue setup
⚙️ Direct commands without make
# Development
uv sync && uv run python -m shared_context_server.scripts.dev

# Testing
uv run pytest --cov=src

# Quality checks
uv run ruff check && uv run mypy src/

License

MIT License - Open source software for the AI community.


Built with modern Python tooling and MCP standards. Contributions welcome!

Metadata

Release files for shared-context-server 1.1.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for shared-context-server 1.1.10
File Size Uploaded Provenance Actions
shared_context_server-1.1.10.tar.gz 367.4 kB Without provenance Details for shared_context_server-1.1.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for shared-context-server 1.1.10
File Interpreter ABI Platform Actions
shared_context_server-1.1.10-py3-none-any.whl Python 3 none any Details for shared_context_server-1.1.10-py3-none-any.whl

Total release size: 547.2 kB

Release files / shared_context_server-1.1.10.tar.gz

Download URL shared_context_server-1.1.10.tar.gz
Size 367.4 kB
Tags Source
SHA-256 checksum
How to use checksums
3d8dab3e795ae927cc1b78c100670d1587c7fd9f753b31b4c578d5b60b2b7976
BLAKE2b-256 checksum
How to use checksums
d3d5a9b9e484e74c45a4fe5ad7cb6fe818644c25c20fd3938be6bee4844a8d1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.13

Release files / shared_context_server-1.1.10-py3-none-any.whl

Download URL shared_context_server-1.1.10-py3-none-any.whl
Size 179.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c2dc124388474900967dde7c585ca8ca1db1d003d6c5ca0418fbdd52bb56f9d7
BLAKE2b-256 checksum
How to use checksums
3d35d929949d3ad90d08800c680347d3dcc639c0f766e2c4d264efb8eb70c6f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.13

Security for shared-context-server 1.1.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page