MCP Server Setup

Overview

The Model Context Protocol (MCP) enables AI assistants to access external tools. th0th provides an MCP server that exposes semantic search, memory, and compression capabilities to any MCP-compatible client.

Supported Clients

th0th MCP server works with:

OpenCode

Recommended AI coding assistant with native MCP support

Claude Desktop

Anthropic’s desktop app with MCP integration

VSCode

Via Copilot or Antigravity extensions

Custom Clients

Any MCP-compatible client via stdio

Prerequisites

Install th0th

git clone <repo-url>
cd th0th
bun install
bun run build

Setup and start API

# Run local-first setup (Ollama)
./scripts/setup-local-first.sh

# Start the API
bun run start:api

Verify: curl http://localhost:3333/health

Install MCP package (optional)

For production use, install the published package:

# Via npm
npm install -g @th0th-ai/mcp-client

# Via bun
bun add -g @th0th-ai/mcp-client

For development, you can run directly from source.

Configuration by Client

OpenCode

Via Package
Via Plugin
From Source

Edit ~/.config/opencode/opencode.json:

opencode.json

{
  "mcpServers": {
    "th0th": {
      "type": "local",
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      },
      "enabled": true
    }
  }
}

opencode.json

{
  "plugin": ["@th0th-ai/opencode-plugin"]
}

opencode.json

{
  "mcpServers": {
    "th0th": {
      "type": "local",
      "command": ["bun", "run", "/path/to/th0th/apps/mcp-client/src/index.ts"],
      "enabled": true
    }
  }
}

See OpenCode Integration for detailed instructions.

Claude Desktop

macOS
Windows
Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "th0th": {
      "command": "bunx",
      "args": ["@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      }
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "th0th": {
      "command": "npx",
      "args": ["@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      }
    }
  }
}

Edit ~/.config/Claude/claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "th0th": {
      "command": "bunx",
      "args": ["@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

VSCode

Create .vscode/mcp.json in your workspace:

.vscode/mcp.json

{
  "servers": {
    "th0th": {
      "command": "bunx",
      "args": ["@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      }
    }
  }
}

Or use the automated setup:

./scripts/setup-vscode.sh

See VSCode Integration for detailed instructions.

Docker

Use the MCP service from docker-compose:

{
  "mcpServers": {
    "th0th": {
      "type": "local",
      "command": ["docker", "compose", "run", "--rm", "-i", "mcp"],
      "enabled": true
    }
  }
}

Run from the th0th directory, or use -f /path/to/docker-compose.yml to specify the file location.

See Docker Integration for detailed instructions.

MCP Client CLI

The MCP client includes a configuration CLI for managing settings.

Quick Config Commands

# Show current configuration
npx @th0th-ai/mcp-client --config-show

# Show config file path
npx @th0th-ai/mcp-client --config-path

# Show config directory
npx @th0th-ai/mcp-client --config-dir

# Initialize configuration
npx @th0th-ai/mcp-client --config-init

# Show help
npx @th0th-ai/mcp-client --help

Initialize with Specific Provider

# Ollama (default)
npx @th0th-ai/mcp-client --config-init

# Mistral
npx @th0th-ai/mcp-client --config-init --mistral your-api-key

# OpenAI
npx @th0th-ai/mcp-client --config-init --openai your-api-key

# Ollama with specific model
npx @th0th-ai/mcp-client --config-init --ollama-model bge-m3

Set Specific Values

# Set embedding dimensions
npx @th0th-ai/mcp-client --config-set embedding.dimensions 1024

# Set API timeout
npx @th0th-ai/mcp-client --config-set api.timeout 30000

Configuration File

The MCP client stores configuration in ~/.config/th0th/config.json:

~/.config/th0th/config.json

{
  "embedding": {
    "provider": "ollama",
    "model": "nomic-embed-text:latest",
    "dimensions": 768,
    "baseUrl": "http://localhost:11434"
  },
  "api": {
    "url": "http://localhost:3333",
    "timeout": 30000
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  }
}

The config file is auto-created on first run with sensible defaults.

Environment Variables

Override config values with environment variables:

Variable	Description	Default
`TH0TH_API_URL`	th0th API endpoint	`http://localhost:3333`
`OLLAMA_BASE_URL`	Ollama server URL	`http://localhost:11434`
`OLLAMA_EMBEDDING_MODEL`	Embedding model	`nomic-embed-text:latest`
`OLLAMA_EMBEDDING_DIMENSIONS`	Embedding dimensions	`768`
`MISTRAL_API_KEY`	Mistral API key	-
`OPENAI_API_KEY`	OpenAI API key	-

Example:

{
  "mcpServers": {
    "th0th": {
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://192.168.1.100:3333",
        "OLLAMA_BASE_URL": "http://192.168.1.100:11434",
        "OLLAMA_EMBEDDING_MODEL": "bge-m3"
      }
    }
  }
}

Testing the Connection

Manual Test

Test the MCP server directly:

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  bunx @th0th-ai/mcp-client

# Expected output: JSON with 7 th0th tools

Via Client

In your AI assistant, try:

List all available MCP tools

You should see:

th0th_index
th0th_search
th0th_remember
th0th_recall
th0th_compress
th0th_optimized_context
th0th_analytics

Available MCP Tools

th0th_index

Index a project directory for semantic search.Parameters:

projectPath (string) - Absolute path to project
projectId (string, optional) - Unique identifier

Returns: Indexing status and statistics

th0th_search

Semantic + keyword search with filters.Parameters:

query (string) - Search query
projectId (string) - Target project
filters (object, optional) - File patterns, etc.
limit (number, optional) - Max results (default: 10)

Returns: Ranked search results with snippets

th0th_remember

Store important information in persistent memory.Parameters:

content (string) - Information to remember
type (string, optional) - decision, fact, note, etc.
tags (array, optional) - Searchable tags

Returns: Memory ID and timestamp

th0th_recall

Search stored memories from previous sessions.Parameters:

query (string) - What to recall
limit (number, optional) - Max results
filters (object, optional) - Type, date range, etc.

Returns: Relevant memories with metadata

th0th_compress

Compress context while preserving structure.Parameters:

content (string) - Content to compress
strategy (string, optional) - code_structure, summarize
targetReduction (number, optional) - Desired % reduction

Returns: Compressed content and stats

th0th_optimized_context

Search + compress in one call for max efficiency.Parameters:

query (string) - Search query
projectId (string) - Target project
maxTokens (number, optional) - Token budget

Returns: Compressed search results ready for LLM

th0th_analytics

View usage patterns and performance metrics.Parameters:

timeRange (string, optional) - day, week, month
metrics (array, optional) - Specific metrics to return

Returns: Analytics data and insights

See MCP Tools Reference for detailed documentation.

Advanced Configuration

Multiple th0th Instances

Connect to multiple th0th servers:

{
  "mcpServers": {
    "th0th-local": {
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      }
    },
    "th0th-remote": {
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://remote-server:3333"
      }
    }
  }
}

Custom Timeout

Increase timeout for large projects:

{
  "mcpServers": {
    "th0th": {
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_TIMEOUT": "60000"
      }
    }
  }
}

Debug Mode

Enable verbose logging:

{
  "mcpServers": {
    "th0th": {
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "DEBUG": "th0th:*",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Troubleshooting

Server not starting

Check the API is running:

curl http://localhost:3333/health

If not:

cd th0th
bun run start:api

Tools not appearing

Test the MCP client directly:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  bunx @th0th-ai/mcp-client

Common issues:

Wrong TH0TH_API_URL in config
API not running or not healthy
Client not restarted after config change

Permission denied

Ensure the MCP client is executable:

# For global install
npm install -g @th0th-ai/mcp-client

# Or use bunx/npx which handle permissions
bunx @th0th-ai/mcp-client --help

Connection timeout

The API may be slow to start or under heavy load:

Check API logs for errors
Increase timeout in config
Verify network connectivity
Check if Ollama is running (for embeddings)

Invalid JSON-RPC

Ensure you’re using the correct MCP protocol version:

# Check MCP client version
bunx @th0th-ai/mcp-client --version

# Update to latest
bunx @th0th-ai/mcp-client@latest --version

Next Steps

MCP Tools Reference

Detailed documentation for all MCP tools

Configuration

Configure embedding providers and models

OpenCode Integration

Optimize for OpenCode usage

VSCode Integration

Setup with VSCode Copilot

Get Started

Integration

Core Concepts

Configuration

Operations

MCP Server Setup

Overview

Supported Clients

OpenCode

Claude Desktop

VSCode

Custom Clients

Prerequisites

Configuration by Client

OpenCode

Claude Desktop

VSCode

Docker

MCP Client CLI

Quick Config Commands

Initialize with Specific Provider

Set Specific Values

Configuration File

Environment Variables

Testing the Connection

Manual Test

Via Client

Available MCP Tools

Advanced Configuration

Multiple th0th Instances

Custom Timeout

Debug Mode

Troubleshooting

Next Steps

MCP Tools Reference

Configuration

OpenCode Integration

VSCode Integration

Build docs developers (and LLMs) love

Get Started

Integration

Core Concepts

Configuration

Operations

Documentation Index

​Overview

​Supported Clients

OpenCode

Claude Desktop

VSCode

Custom Clients

​Prerequisites

​Configuration by Client

​OpenCode

​Claude Desktop

​VSCode

​Docker

​MCP Client CLI

​Quick Config Commands

​Initialize with Specific Provider

​Set Specific Values

​Configuration File

​Environment Variables

​Testing the Connection

​Manual Test

​Via Client

​Available MCP Tools

​Advanced Configuration

​Multiple th0th Instances

​Custom Timeout

​Debug Mode

​Troubleshooting

​Next Steps

MCP Tools Reference

Configuration

OpenCode Integration

VSCode Integration

Build docs developers (and LLMs) love

Overview

Supported Clients

Prerequisites

Configuration by Client

OpenCode

Claude Desktop

VSCode

Docker

MCP Client CLI

Quick Config Commands

Initialize with Specific Provider

Set Specific Values

Configuration File

Environment Variables

Testing the Connection

Manual Test

Via Client

Available MCP Tools

Advanced Configuration

Multiple th0th Instances

Custom Timeout

Debug Mode

Troubleshooting

Next Steps