TUP MCP Server

Telepathy Universal Protocol — Model Context Protocol Bridge

Secure, zero-shared-state AI-to-AI collaboration across organizations.

---

🌐 What is TUP MCP Server?

tup-mcp-server is an open-source Model Context Protocol (MCP) server that enables AI agents from different organizations to collaborate securely — without sharing system prompts, private data, model weights, or internal memory.

It implements the Telepathy Universal Protocol (TUP), a governed AI-to-AI communication standard built on the principle of Zero-Shared-State.

Key Features

• 🔒 Zero-Shared-State: Agents exchange validated semantic vectors (Intents), never raw data or prompts.
• ⚡ Streamable HTTP Relay: Stateless relay server using chunked HTTP streaming — no WebSocket overhead.
• 🧮 4-Fold Mathematical Validation: Condition number, round-trip, orthogonality, and eigenvalue stability checks.
• 🔁 Open Core Architecture: Works out-of-the-box with a pure-Python fallback; drops in the high-performance telepathy-tup engine for enterprise speed.
• 🛡️ DNS Rebinding Protection: Origin and Host header validation on every request.

---

🏗️ Architecture

[ Agent A ] ──(MCP Tool)──► [ tup-mcp-server A ] ──(HTTP)──► [ relay ] ──(HTTP)──► [ tup-mcp-server B ] ──(MCP)──► [ Agent B ]

Component	License	Description
tup-mcp-server	MIT	MCP server exposing TUP tools to Claude and other agents
relay.py	MIT	Stateless Streamable HTTP relay routing encrypted intents
tup_core_fallback.py	MIT	Pure-Python reference TUP engine (ActionSpec, Intent, Channel)
telepathy-tup	Proprietary	Optional high-performance Cython core (drop-in replacement)

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• pip

Installation

# Clone the repository
git clone https://github.com/telepathy-TUP/tup-mcp-server.git
cd tup-mcp-server

# Install dependencies
pip install -e ".[dev]"

Run the Relay Server

python relay.py
# Relay starts at http://localhost:8000

Run the MCP Server

python mcp_server.py

Configure Claude Desktop

Copy mcp_config.json into your Claude Desktop configuration directory, or add the following to your existing config:

{
  "mcpServers": {
    "tup-mcp-server": {
      "command": "python",
      "args": ["path/to/mcp_server.py"],
      "env": {
        "TUP_RELAY_URL": "http://localhost:8000"
      }
    }
  }
}

---

🔧 MCP Tools

Tool	Description
tup_connect	Establishes a session with the relay server
tup_send_intent	Constructs, validates, and sends a semantic intent
tup_get_pending_intents	Retrieves received intents from the session queue
tup_get_session_status	Returns channel state, metrics, and fallback status
tup_transition_state	Transitions the channel state machine

Example Usage

1. tup_connect(relay_url="http://localhost:8000", session_id="collab-01", role="agent_a", partner_role="agent_b")
2. tup_send_intent(session_id="collab-01", vector=[0.5, 0.3, -0.1], operation="ALIGN", direction="FORWARD", cardinality=3, output_dimensions=128)
3. tup_get_pending_intents(session_id="collab-01")
4. tup_get_session_status(session_id="collab-01")

---

🧮 Mathematical Validation

The fallback core implements a rigorous 4-fold validation on transformation matrices:

1. Condition Number: numpy.linalg.cond(A) ≤ 10¹⁰
2. Round-Trip Check: A × A⁻¹ ≈ I with tolerance 1e-8
3. Orthogonality Check: A × Aᵀ ≈ I (norm-preserving optimization)
4. Eigenvalue Stability: |λ| ≤ 1 for all eigenvalues (prevents divergence)

---

🧪 Running Tests

python -m pytest -v

All 16 tests cover:

• test_fallback_compatibility.py — Core math, state machine, hash integrity
• test_mcp_tools.py — MCP tool registration, matrix rejection, intent lifecycle
• test_relay_flow.py — DNS rebinding protection, intent routing, session management

---

📂 Project Structure

tup-mcp-server/
├── pyproject.toml              # Package configuration & dependencies
├── mcp_config.json             # Example Claude Desktop config
├── mcp_server.py               # MCP server (FastMCP + dynamic fallback)
├── relay.py                    # Stateless Streamable HTTP relay (FastAPI)
├── tup_core_fallback.py        # Pure-Python TUP engine (MIT)
├── README.md                   # This file
└── tests/
    ├── test_fallback_compatibility.py
    ├── test_mcp_tools.py
    └── test_relay_flow.py

---

📜 License

This project is licensed under the MIT License. See LICENSE for details.

The optional high-performance engine telepathy-tup is proprietary and commercially licensed.

---

---

TUP MCP Server (Español)

Telepathy Universal Protocol — Puente de Protocolo de Contexto de Modelo

Colaboración segura entre agentes de IA sin compartir estado.

---

🌐 ¿Qué es TUP MCP Server?

tup-mcp-server es un servidor de código abierto compatible con el Model Context Protocol (MCP) que permite a agentes de IA de distintas organizaciones colaborar de forma segura — sin compartir prompts del sistema, datos privados, pesos de modelo ni memoria interna.

Implementa el Telepathy Universal Protocol (TUP), un estándar de comunicación gobernada IA-a-IA construido sobre el principio de Cero Estado Compartido (Zero-Shared-State).

Características Principales

• 🔒 Cero Estado Compartido: Los agentes intercambian vectores semánticos validados (Intents), nunca datos crudos ni prompts.
• ⚡ Relay Streamable HTTP: Servidor de retransmisión sin estado usando streaming HTTP chunked — sin sobrecarga de WebSocket.
• 🧮 Validación Matemática de 4 Niveles: Número de condición, round-trip, ortogonalidad y estabilidad de autovalores.
• 🔁 Arquitectura Open Core: Funciona out-of-the-box con un fallback en Python puro; acepta el motor de alto rendimiento telepathy-tup como reemplazo directo para velocidad empresarial.
• 🛡️ Protección contra DNS Rebinding: Validación de headers Origin y Host en cada solicitud.

---

🚀 Inicio Rápido

Requisitos

• Python 3.10+
• pip

Instalación

# Clonar el repositorio
git clone https://github.com/telepathy-TUP/tup-mcp-server.git
cd tup-mcp-server

# Instalar dependencias
pip install -e ".[dev]"

Ejecutar el Relay

python relay.py
# El relay se inicia en http://localhost:8000

Ejecutar el Servidor MCP

python mcp_server.py

Configurar Claude Desktop

Copie mcp_config.json al directorio de configuración de Claude Desktop, o agregue lo siguiente a su configuración existente:

{
  "mcpServers": {
    "tup-mcp-server": {
      "command": "python",
      "args": ["ruta/a/mcp_server.py"],
      "env": {
        "TUP_RELAY_URL": "http://localhost:8000"
      }
    }
  }
}

---

🔧 Herramientas MCP

Herramienta	Descripción
tup_connect	Establece una sesión con el servidor relay
tup_send_intent	Construye, valida y envía una intención semántica
tup_get_pending_intents	Recupera intents recibidos de la cola de sesión
tup_get_session_status	Devuelve estado del canal, métricas e indicador de fallback
tup_transition_state	Transiciona la máquina de estados del canal

---

🧪 Ejecutar Pruebas

python -m pytest -v

Las 16 pruebas cubren:

• test_fallback_compatibility.py — Matemáticas del core, máquina de estados, integridad de hashes
• test_mcp_tools.py — Registro de herramientas MCP, rechazo de matrices, ciclo de vida de intents
• test_relay_flow.py — Protección DNS rebinding, enrutamiento de intents, gestión de sesiones

---

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Ver LICENSE para detalles.

El motor de alto rendimiento opcional telepathy-tup es propietario y tiene licencia comercial.