Tether MCP

The anti-drift engine for AI coding agents.
Give your AI persistent memory of your project's rules. One command. Zero cloud.

AI agents like Cursor and Claude write code fast — but they suffer fromAgent Drift: hallucinating dependencies, violating architectural boundaries, and creating spaghetti code. Tether is a persistentSenior Architectthat your AI must consult before making structural changes.

- The Problem
- Quick Start
- How It Works
- Tools
- MCP Resources
- CLI Commands
- Configuration
- Dependency Severity Levels
- The Decision Ledger
- Session Telemetry
- Supported Frameworks
- Config Reference
- FAQ
- Contributing
- License

{ "mcpServers": { "tether": { "command": "npx", "args": ["-y", "tether-mcp"] } } }

Add to.cursor/mcp.jsonin your project root:

{ "mcpServers": { "tether": { "command": "npx", "args": ["-y", "tether-mcp"] } } }

{ "mcpServers": { "tether": { "command": "npx", "args": ["-y", "tether-mcp"] } } }

3. Done. Your AI Agent Now Has Guardrails ⚓

Every time the AI starts working, it consults Tether first — reading your invariants, checking dependency policies, validating file placements, and logging structural decisions. No more drift.

┌──────────────┐ MCP Tools ┌──────────────┐ Local Files ┌──────────────────┐ │ AI Agent │ ◄──────────────► │ Tether MCP │ ◄─────────────────► │ tether.config.json│ │ (Claude, │ │ Server │ │ ARCHITECTURE.md │ │ Cursor) │ │ │ │ DECISIONS.md │ └──────────────┘ └──────────────┘ └──────────────────┘

Edittether.config.jsonto match your project:

{ "projectName": "my-app", "techStack": { "frontend": ["Next.js", "React"], "backend": ["Node.js"], "orm": ["Prisma"] }, "invariants": [ "All API routes must validate input with Zod.", "Database access must go through Prisma — no raw SQL.", "Use Server Components by default — client components only when needed." ], "dependencies": { "blocked": [ { "name": "moment", "reason": "Use date-fns instead.", "alternatives": ["date-fns"], "severity": "block" }, { "name": "lodash", "reason": "Tree-shaking issues. Use native JS or lodash-es.", "alternatives": ["lodash-es", "remeda"], "severity": "warn" } ] }, "fileStructure": [ { "pattern": "component", "allowedPaths": ["src/components/", "src/app/"], "reason": "All React components must live in src/components/ or src/app/" }, { "pattern": "api-route", "allowedPaths": ["src/app/api/"], "reason": "API routes must use Next.js Route Handlers in app/api/" } ], "codePatterns": [ { "name": "State Management", "rule": "Use React Context + useReducer for complex state — no Redux or Zustand", "scope": "frontend/state" }, { "name": "Data Fetching", "rule": "Use Server Components for data fetching — no client-side fetch in components", "scope": "frontend" } ] }

npx tether-mcp init # Scan project & generate tether.config.json npx tether-mcp serve # Start the MCP server (stdio) npx tether-mcp status # Show project config summary & health npx tether-mcp validate # Validate tether.config.json against schema npx tether-mcp --version # Show version npx tether-mcp --help # Show all commands

Blocked dependencies now supportseverity levels:

{ "dependencies": { "blocked": [ { "name": "moment", "reason": "Deprecated.", "alternatives": ["date-fns"], "severity": "block" }, { "name": "axios", "reason": "Prefer native fetch.", "alternatives": ["fetch"], "severity": "warn" } ] } }

When you runnpx tether-mcp initin a Next.js + Prisma + Tailwind project, Tether generates:

{ "projectName": "my-next-app", "techStack": { "frontend": ["Next.js", "React"], "styling": ["Tailwind CSS"], "orm": ["Prisma"], "language": ["TypeScript"] }, "invariants": [ "Use Next.js App Router for all new routes — do not use the Pages Router.", "All database access must go through Prisma — no raw SQL queries.", "Use Tailwind utility classes for styling — no inline styles.", "All new code must be written in TypeScript with strict mode enabled." ], "dependencies": { "blocked": [ { "name": "express", "reason": "Next.js has built-in API routes.", "alternatives": ["Next.js Route Handlers"] }, { "name": "moment", "reason": "Deprecated and large bundle size.", "alternatives": ["date-fns"] } ] } }

Every structural decision the AI makes is logged inDECISIONS.md:

## Added Redis caching layer | Field | Value | |-------|-------| | Date | 2026-03-10T01:30:00.000Z | | Scope | api/cache | ### Summary Added Redis via ioredis for caching frequently accessed product data. Chose Redis over Memcached for pub/sub support and persistence options.

This creates animmutable audit trailof every architectural choice — visible to the next developerandthe next AI session.

Thehealth_checktool returns local-only session statistics:

{ "status": "healthy", "session": { "sessionStartedAt": "2026-03-12T10:00:00.000Z", "totalCalls": 7, "toolStats": { "get_project_invariants": { "callCount": 3, "lastCalledAt": "...", "errors": 0 }, "verify_dependency_addition": { "callCount": 2, "lastCalledAt": "...", "errors": 0 } } } }

No data leaves your machine. Telemetry resets when the server restarts.

Tether auto-detects90 frameworksacross8 ecosystems:

JavaScript / TypeScript (package.json)

Python (pyproject.toml,requirements.txt)

Java / Kotlin (build.gradle,pom.xml)

Each detection addstargeted invariantsandsmart blocked-package rulesspecific to your stack.

No.Runnpx tether-mcp initand it auto-generatestether.config.jsonby scanning your project. You can customize it afterward, but the defaults are smart enough out of the box.

No.MCP tools are auto-discovered. The AI sees Tether's tools in its toolbox and calls them when making structural changes — just like it usesfile_readorterminal.

~500-1,500 tokens per session for guardrails vs.5,000-20,000 tokenswasted fixing drift mistakes. Tether pays for itself in the first blocked bad dependency.

Smart ≠ omniscient. Claude doesn't know your team decided ondate-fnsthree months ago. It doesn't remember Session #1's decisions in Session #10. And when you close the tab, context is gone. Tether gives the AIpersistent, file-based memoryof your rules — across every session, every agent.

Each project gets its owntether.config.jsonin its own directory. Project A's rules never leak into Project B.

No. CLAUDE.md is passive — the AI may or may not read it. Tether isactive— it validates dependencies, blocks bad packages with alternatives, checks file structure, verifies code patterns, and maintains an audit trail. It works across Claude, Cursor, Windsurf, and any MCP-compatible agent.

Contributions are welcome! Here are some ways to help:

- Add a framework signature— detect a new framework insrc/utils/detect-stack.ts
- Improve invariants— better defaults for existing frameworks
- Bug reports— open anissue
- Feature requests— ideas for new tools or resources

git clone https://github.com/MoayadEsam/tether-mcp.git cd tether-mcp npm install npm run build

MIT— built with ♥ for developers who are tired of cleaning up after their AI agents.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB