SMCP Docs

SMCP — Secure Model Context Protocol

MCP with authentication, per-message encryption, and multi-agent (A2A) coordination — so MCP tools run safely over a network and between agents.

Python 3.8+ License: MIT MCP-compatible

🎬 Demo: Multi-Agent Business Intelligence in Action

CrewAI + SMCP Demo

Watch SMCP orchestrate multiple AI agents to generate real business intelligence reports! This demo shows CrewAI + SMCP working together to analyze e-commerce, SaaS, and IoT data using Qwen3 models, DuckDB, and secure multi-agent coordination.

🚀 What SMCP is

MCP is a great way to give an AI model tools, but it’s built for a local, trusted transport (stdio on a single machine). SMCP keeps MCP’s tool model exactly as-is and wraps it in a security + coordination layer, so the same tools work across machines and between agents:

  • 🔒 Authentication — api_key → JWT sessions (with OAuth2 and audit-trail options)
  • 🔐 Encryption — per-message payload encryption (ECDH key exchange + AES-256)
  • 🤝 Multi-agent (A2A) — agent-to-agent discovery and orchestration, sequential or parallel
  • 🔌 Connectors — native DuckDB and filesystem integrations to build tools against
  • ✅ MCP-compatible — the security layer is opt-in; standard MCP tools keep working

Pick the posture that fits — from a simple API key for local testing up to JWT + AES-256 with an audit trail (see Security modes below).

SMCP is a working proof-of-concept: the demos below run end to end. It explores how MCP can be hardened for networked, multi-agent use — the same ideas are used in the RIXI agent (agent/smcp.py) to share tools securely between agents over an untrusted link.

📚 Documentation

Architecture & Design

Technical Guides

✨ Key Features

🔐 Security modes

Choose per deployment — the same tools, a stronger posture as you need it:

  • Simple — API key authentication (local testing)
  • Basic — JWT + HTTPS/TLS
  • Encrypted — ECDH key exchange + AES-256 payload encryption
  • Enterprise — OAuth2 + audit trail

🤖 Agent-to-Agent (A2A) System

  • Multi-agent task orchestration
  • Dynamic agent discovery
  • Parallel and sequential workflows
  • Load balancing and failover

🔌 Native Connectors

  • DuckDB: High-performance analytical queries
  • Filesystem: Secure local storage
  • Extensible: Easy to add custom connectors

🏗️ Technical Features

  • Configuration via TOML/YAML/ENV
  • Logging and monitoring examples
  • Connection pooling experiments
  • Scaling pattern demonstrations

📦 Installation

Prerequisites

  • Python 3.8+
  • Ollama (for AI features)
  • Docker (for MindsDB)
  • Pixi package manager

Quick Start

  1. Clone the repository:
git clone https://github.com/KellerKev/smcp.git
cd smcp
  1. Install dependencies using pixi:
# Install pixi if you don't have it
curl -fsSL https://pixi.sh/install.sh | bash

# Install all dependencies
pixi install
  1. Setup Ollama and AI Models:
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve &

# Pull required models (Qwen models recommended)
ollama pull qwen2.5-coder:7b-instruct-q4_K_M
ollama pull qwen3-coder:30b-a3b-q4_K_M
  1. Initialize DuckDB with Sample Data:
# Generate sample data
pixi run python tools/generate_sample_data.py

# Create database and tables
pixi run python examples/duckdb_integration_example.py
  1. Setup MindsDB (Optional - for ML features):
# Run MindsDB in Docker
docker run -d --name mindsdb_smcp \
  -p 47335:47334 \
  -p 47336:47335 \
  mindsdb/mindsdb

# Verify it's running
curl http://localhost:47335/

📚 Full Setup Guide: See SETUP_GUIDE.md for detailed instructions

🎯 Quick Demo

1. Basic Poem Generation

This demo shows multi-agent AI coordination:

# Start Ollama (in another terminal)
ollama serve

# Run the demo
python examples/basic/basic_poem_sample.py

What happens:

  • TinyLLama generates an initial poem
  • Mistral enhances it
  • Result is securely stored locally
  • Uses JWT authentication

2. DuckDB Analytics Demo

Shows database integration with AI analysis:

# Generate sample data
python tools/generate_sample_data.py

# Run analytics demo
python examples/duckdb_integration_example.py

Features demonstrated:

  • SQL queries via SMCP connector
  • AI-powered data analysis
  • Business intelligence generation

3. Complete System Showcase

See all features in action:

python examples/showcase_complete_system.py

🏃‍♂️ Running Your First SMCP Server

Server Setup

  1. Create configuration (optional):
python smcp_server_main.py --create-config
  1. Start the server:
python smcp_server_main.py

Client Connection

from smcp_client import SMCPClient
from smcp_config import SMCPConfig

# Create configuration
config = SMCPConfig(
    mode="basic",
    server_url="ws://localhost:8765"
)

# Connect and use
client = SMCPClient(config)
await client.connect()

# Discover capabilities
capabilities = client.capabilities

# Invoke a tool
result = await client.invoke_tool("echo", {"message": "Hello SMCP!"})

# Disconnect
await client.disconnect()

🎭 Example Use Cases

Multi-Agent Report Generation

# Demonstrates CrewAI + SMCP for business intelligence
python examples/crewai_report_orchestration.py

Creates executive reports using:

  • Data Analyst agent (queries DuckDB)
  • Business Analyst agent (strategic insights)
  • Report Writer agent (document generation)
  • Quality Reviewer agent (validation)

Secure Enterprise Deployment

# Shows enterprise-grade security features
python examples/encrypted/encrypted_enterprise_sample.py

Features:

  • ECDH key exchange
  • AES-256 encryption
  • Audit trails
  • Compliance logging

📁 Project Structure

smcp/
├── smcp_*.py                 # Core SMCP modules
├── connectors/              # Native connector implementations
│   ├── smcp_duckdb_connector.py
│   └── smcp_filesystem_connector.py
├── examples/                # Demo applications
│   ├── basic/              # Basic security mode examples
│   ├── encrypted/          # Encrypted mode examples
│   └── *.py               # Integration examples
├── tools/                   # Utility scripts
│   ├── generate_sample_data.py
│   └── setup_dev_security.py
├── docs/                    # Documentation
└── sample_data/            # Sample datasets

🔧 Configuration

SMCP supports multiple configuration sources:

TOML Configuration

# smcp_config.toml
[core]
node_id = "production_node"
mode = "basic"  # or "encrypted", "enterprise"

[server]
host = "0.0.0.0"
port = 8765

[security]
jwt_secret = "your-secret-key-min-32-chars"
require_signature = true

Environment Variables

export SMCP_NODE_ID="production_node"
export SMCP_MODE="basic"
export SMCP_JWT_SECRET="your-secret-key"

Python Configuration

from smcp_config import SMCPConfig

config = SMCPConfig(
    mode="basic",
    node_id="my_node",
    jwt_secret="secret_key"
)

🛡️ Security Best Practices

  1. Use appropriate security mode:

    • Development: simple mode
    • Production: basic mode with HTTPS
    • High security: encrypted mode
    • Compliance: enterprise mode

  2. Secure your keys:

    • Use strong JWT secrets (32+ characters)
    • Rotate keys regularly
    • Never commit secrets to version control

  3. Enable HTTPS for deployment:

    config.server_url = "wss://your-domain.com"  # WSS for secure WebSocket

🤝 MCP Compatibility

SMCP is 100% compatible with existing MCP tools and clients:

# Works with standard MCP clients
# SMCP server appears as enhanced MCP server
# All MCP tools continue to work

📊 Performance

  • Message Processing: <10ms overhead for encryption
  • A2A Coordination: <50ms for agent discovery
  • Database Queries: Sub-second on 100K+ records
  • Horizontal Scaling: Supports multiple nodes

🧪 Testing

Run the test suite:

# Compile all examples (syntax check)
find examples/ -name "*.py" -exec python3 -m py_compile {} \;

# Run basic test
python examples/basic/basic_poem_sample.py

📚 Documentation

🤲 Contributing

We welcome contributions! Please see our contributing guidelines.

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

🚦 Status

  • ✅ Core SMCP: Proof-of-concept working
  • ✅ Basic/Encrypted modes: Functional demonstrations
  • ✅ A2A System: Working prototype
  • ✅ DuckDB Connector: Example implementation
  • ✅ CrewAI Integration: Working demo (requires CrewAI)
  • 🚧 Enterprise Mode: Experimental

Want to explore MCP security concepts? Start with the Quick Demo above!

In this documentation