Skip to content

Setting Up Tenets MCP Server: Complete Guide

Author: Johnny Dunn | Date: December 4, 2024

Overview

Tenets is a local MCP server with two core capabilities:

  1. Intelligent code context — NLP-powered ranking finds relevant files automatically
  2. Automatic tenets injection — Your guiding principles are included in every prompt

This guide covers installation, configuration, and verification for all major MCP hosts.

Time required: 5-10 minutes

Prerequisites

Python Environment

Tenets requires Python 3.9+:

Bash
python3 --version
# Python 3.11.x or higher recommended

pip Package Manager

Bash
pip --version
# pip 23.x or higher

MCP-Compatible Host

One of: - Cursor (native MCP support) - Claude Desktop (macOS, Windows) - Windsurf (MCP extension) - VS Code with Continue or MCP extension

Installation

Standard Installation

Bash
pip install tenets[mcp]

This installs: - tenets CLI and Python library - tenets-mcp server binary - MCP protocol dependencies (mcp, httpx)

Verify Installation

Bash
tenets-mcp --version
# tenets-mcp v0.7.x

which tenets-mcp
# /usr/local/bin/tenets-mcp (or your Python bin path)

Save this path—you'll need it for configuration.

Optional: ML Features

For semantic embeddings (slower but more accurate):

Bash
pip install tenets[ml]

Adds sentence-transformers for embedding-based ranking.

Cursor Configuration

Cursor has native MCP support. Configuration lives in ~/.cursor/mcp.json.

Step 1: Create/Edit Config

Bash
# Create directory if needed
mkdir -p ~/.cursor

# Edit config
nano ~/.cursor/mcp.json

Step 2: Add Tenets Server

Minimal configuration:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp"
    }
  }
}

With full path (recommended for reliability):

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "/usr/local/bin/tenets-mcp"
    }
  }
}

With environment variables:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp",
      "env": {
        "TENETS_LOG_LEVEL": "DEBUG",
        "TENETS_CACHE_DIR": "/tmp/tenets-cache"
      }
    }
  }
}

Step 3: Restart Cursor

Fully quit and reopen Cursor (not just reload window).

Step 4: Verify

In Cursor's AI chat:

Text Only
What MCP tools do you have available?

You should see distill, rank_files, examine, etc.

Claude Desktop Configuration

macOS

Config path: ~/Library/Application Support/Claude/claude_desktop_config.json

Bash
# Create directory
mkdir -p ~/Library/Application\ Support/Claude

# Create/edit config
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Configuration:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "/usr/local/bin/tenets-mcp"
    }
  }
}

Windows

Config path: %APPDATA%\Claude\claude_desktop_config.json

PowerShell
# Open config location
explorer %APPDATA%\Claude

Configuration:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "C:\\Users\\YourName\\AppData\\Local\\Programs\\Python\\Python311\\Scripts\\tenets-mcp.exe"
    }
  }
}

Find your path:

PowerShell
where tenets-mcp

Restart Claude Desktop

Quit and reopen the application.

Windsurf Configuration

Windsurf uses VS Code-style settings with MCP extension.

Step 1: Open Settings

Cmd/Ctrl + , → Search "MCP"

Step 2: Edit JSON

JSON
{
  "mcp.servers": {
    "tenets": {
      "command": "tenets-mcp"
    }
  }
}

Step 3: Restart

Reload Windsurf window.

VS Code with Continue

Continue extension provides MCP support for VS Code.

Step 1: Install Continue

Install from VS Code marketplace.

Step 2: Configure MCP

Open Continue settings and add:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp"
    }
  }
}

Advanced Configuration

Project-Specific Servers

Run different Tenets instances for different projects:

JSON
{
  "mcpServers": {
    "tenets-frontend": {
      "command": "tenets-mcp",
      "args": ["--path", "/home/user/projects/frontend"]
    },
    "tenets-backend": {
      "command": "tenets-mcp",
      "args": ["--path", "/home/user/projects/backend"]
    },
    "tenets-infra": {
      "command": "tenets-mcp",
      "args": ["--path", "/home/user/projects/infrastructure"]
    }
  }
}

Debug Mode

Enable verbose logging:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp",
      "env": {
        "TENETS_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Custom Config File

Point to a specific .tenets.yml:

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp",
      "env": {
        "TENETS_CONFIG": "/path/to/.tenets.yml"
      }
    }
  }
}

Verification

Test 1: Tool Discovery

Ask your AI:

Text Only
What tools are available from tenets?

Expected response: - distill — Build optimized code context - rank_files — Preview file relevance scores - examine — Analyze codebase structure - session_create, session_pin_file, etc.

Test 2: Basic Distill

Text Only
Use tenets to find code related to user authentication in /path/to/project

Expected: The AI calls distill and returns ranked code context.

Test 3: Examine Codebase

Text Only
Use tenets examine on /path/to/project

Expected: Structure analysis with file counts, languages, complexity.

Test 4: Session Creation

Text Only
Create a tenets session called "auth-feature"

Expected: Confirmation of session creation.

Troubleshooting

"Command not found"

Cause: Shell can't find tenets-mcp binary.

Fix: Use absolute path:

Bash
# Find the path
which tenets-mcp
# /home/user/.local/bin/tenets-mcp

# Use in config
{
  "mcpServers": {
    "tenets": {
      "command": "/home/user/.local/bin/tenets-mcp"
    }
  }
}

"Server not responding"

Cause: Server crashes on startup.

Debug:

Bash
# Run manually to see errors
tenets-mcp

# Check for Python errors
python -c "import tenets; print(tenets.__version__)"

Common fixes:

Bash
# Upgrade to latest
pip install tenets[mcp] --upgrade

# Reinstall
pip uninstall tenets && pip install tenets[mcp]

"Tools not appearing"

Cause: Config not loaded or JSON syntax error.

Debug:

  1. Validate JSON syntax: https://jsonlint.com
  2. Check config file path is correct
  3. Fully restart application (not just reload)

"Permission denied"

Cause: Binary not executable.

Fix:

Bash
chmod +x $(which tenets-mcp)

Server Hangs on Large Codebases

Cause: Scanning too many files.

Fix: Add excludes to .tenets.yml:

YAML
scanner:
  exclude:
    - node_modules/
    - .git/
    - dist/
    - build/
    - "*.min.js"

Server Logs

Enable Debug Logging

JSON
{
  "mcpServers": {
    "tenets": {
      "command": "tenets-mcp",
      "env": {
        "TENETS_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Manual Server Testing

Bash
# Run server and send test request
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | tenets-mcp

Log File Location

Logs write to stderr by default. Capture them:

Bash
tenets-mcp 2>&1 | tee /tmp/tenets-mcp.log

Performance Tuning

For Large Codebases (>10k files)

YAML
# .tenets.yml
scanner:
  max_files: 5000  # Limit scan
  exclude:
    - "*.generated.*"
    - vendor/
    - third_party/

ranking:
  algorithm: fast  # Use faster mode by default

For Slow Machines

YAML
context:
  max_tokens: 50000  # Reduce token budget

ranking:
  use_ml: false  # Disable ML features

Next Steps

Now that Tenets is configured:

  1. Try distill: Ask your AI to find code for a specific task
  2. Create sessions: Pin files you reference repeatedly
  3. Add tenets: Define guiding principles (coding standards, architecture rules) that auto-inject into every prompt
  4. Explore modes: Test fast vs balanced vs thorough

The combination of intelligent context + automatic tenets injection helps maintain consistency across long conversations where context would otherwise drift.

Resources