MCP Integration#

Configure Semantiq with Claude Code, Cursor, Windsurf, and other AI tools.

What is MCP?#

MCP (Model Context Protocol) is an open standard that allows AI assistants to communicate with external tools and services. Semantiq implements MCP to provide semantic code understanding to any compatible AI tool.

Tool Compatibility#

Semantiq works with any MCP-compatible AI tool. Here are configuration examples for popular tools:

Claude Code (CLI)#

Automatic configuration:

npx semantiq-mcp init

Or manually edit .claude/settings.json:

1{
2  "mcpServers": {
3    "semantiq": {
4      "command": "npx",
5      "args": ["-y", "semantiq-mcp", "serve"]
6    }
7  }
8}

Claude Desktop#

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

1{
2  "mcpServers": {
3    "semantiq": {
4      "command": "npx",
5      "args": ["-y", "semantiq-mcp", "serve"],
6      "cwd": "/path/to/your/project"
7    }
8  }
9}

Cursor#

Automatic configuration:

npx semantiq-mcp init-cursor

Or manually create .cursor/mcp.json:

1{
2  "mcpServers": {
3    "semantiq": {
4      "command": "npx",
5      "args": ["-y", "semantiq-mcp", "serve"]
6    }
7  }
8}

Windsurf#

Create .windsurf/mcp.json in your project:

1{
2  "mcpServers": {
3    "semantiq": {
4      "command": "npx",
5      "args": ["-y", "semantiq-mcp", "serve"]
6    }
7  }
8}

VS Code + Continue#

Add to ~/.continue/config.json:

1{
2  "experimental": {
3    "modelContextProtocolServers": [
4      {
5        "transport": {
6          "type": "stdio",
7          "command": "npx",
8          "args": ["-y", "semantiq-mcp", "serve"]
9        }
10      }
11    ]
12  }
13}

JetBrains IDEs#

JetBrains IDEs (2025.2+) support MCP natively. Check the JetBrains documentation for configuration instructions.

Important: After configuration, index your project:

semantiq index .

Semantic Search#

Semantiq combines 4 search strategies:

How It Works#

1. Semantic Search - Uses embeddings (MiniLM-L6-v2) to find conceptually similar code
2. Lexical Search - Fast regex search with ripgrep for exact matches
3. Symbol Search - FTS5-powered search of function/class/variable names
4. Dependency Analysis - Graph traversal to understand code relationships

For example, searching for "authentication handler" will find functions like handleLogin, verifyToken, or checkAuth even if they don't contain those exact words.

Available Tools#

Semantiq provides 4 MCP tools for AI assistants:

semantiq_search#

Semantic + lexical code search combining 4 strategies.

1{
2  "query": "string",       // Required: Search query
3  "limit": 20,             // Optional: max results (default: 20)
4  "min_score": 0.35,       // Optional: minimum similarity (default: 0.35)
5  "file_type": "string",   // Optional: filter by extension (e.g., "ts")
6  "symbol_kind": "string"  // Optional: filter by kind (function, class, etc.)
7}

semantiq_find_refs#

Find all references to a symbol including definitions and usages.

1{
2  "symbol": "string",  // Required: Symbol name to find
3  "limit": 50          // Optional: max results (default: 50)
4}

semantiq_deps#

Analyze the dependency graph for a file. Shows imports and dependents.

{
  "file_path": "string"  // Required: File path to analyze
}

semantiq_explain#

Get detailed explanation of a symbol including definition, documentation, and usage patterns.

{
  "symbol": "string"  // Required: Symbol name to explain
}

Semantiq vs grep/find#

For a detailed comparison with grep/find, see Semantiq vs grep/find.

Auto-Indexing#

When running as an MCP server, Semantiq automatically watches for file changes and updates the index in real-time. No manual re-indexing needed after initial setup.

Troubleshooting#

Server not starting#

Verify Semantiq is installed correctly by running semantiq --version in your terminal.

Empty search results#

Make sure your project is indexed. Run semantiq index . in your project root. Check that .semantiq.db exists.

Stale results#

If auto-indexing seems stuck, run semantiq index --force to rebuild the entire index.

See Also#

• CLI Reference - Complete command documentation
• Usage Guide - Practical examples for each tool
• Optimal Workflow - Combine Semantiq with native tools