Senzing MCP Server

Model Context Protocol (MCP) server for the Senzing SDK, providing entity resolution capabilities to Claude and other MCP clients.

Overview

This MCP server exposes Senzing SDK functionality through the Model Context Protocol, enabling AI assistants like Claude to:

• Search for entities by attributes

• Retrieve detailed entity information

• Analyze relationships and networks

• Explain entity resolution decisions (HOW and WHY analysis)

Features

This is a read-only MCP server providing 7 tools for entity resolution analysis:

Entity Search & Retrieval

• search_entities: Search by name, address, phone, email, etc.

• get_entity: Retrieve detailed entity information by entity ID

• get_source_record: Look up entity by source record ID (e.g., CUSTOMERS:1001)

Relationship Analysis

• find_path: Discover paths between entities

• expand_network: Expand networks of related entities to (n) degrees (max 3)

• explain_why_related: Explain why two entities are related (WHY analysis)

• explain_how_resolved: See how entities were resolved (HOW analysis)

Installation

Prerequisites

• Python 3.10 or higher

• Senzing SDK version 4 installed and environment initialized

• Senzing database configured and accessible

Setup

1. Clone the repository to your server:

2. Install Python dependencies:

3. Make the launch script executable:

Note: The server runs directly from source after installing dependencies. Environment variables are configured in your AI assistant's MCP configuration (see Configuration section below).

Usage

Running the Server

The server supports two transport modes: STDIO (default) and HTTP/SSE.

STDIO Transport (Default)

STDIO is the default transport where the AI assistant spawns the server as a subprocess:

HTTP/SSE Transport

HTTP/SSE runs the server as a long-running process that AI clients connect to via HTTP:

The server will display the connection URL:

When to use HTTP/SSE:

• Server persists across AI sessions (SDK stays initialized)

• Multiple AI clients can connect to one server

• Simpler remote access (no SSH wrapper needed)

• Better for production deployments

Configuration for AI Assistants

This MCP server works with any MCP-compatible AI assistant. Below are detailed instructions for Claude (Desktop and Code), plus guidance for other assistants.

Claude Desktop Configuration

Add to your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Notes:

• command: Full path to the launch_senzing_mcp.sh script

• SENZING_ENGINE_CONFIGURATION_JSON: Your Senzing database configuration (must be escaped JSON)

• LD_LIBRARY_PATH: Path to Senzing shared libraries

• PYTHONPATH: Path to Senzing Python SDK (if not system-wide installed)

Optional environment variables:

• SENZING_MODULE_NAME: Module identifier (default: "senzing-mcp")

• SENZING_INSTANCE_NAME: Instance name (default: "senzing-mcp-server")

• SENZING_LOG_LEVEL: Verbosity level (default: 0)

Claude Code Configuration

Claude Code (the CLI tool at claude.ai/code) uses the same MCP configuration as Claude Desktop. Configure in your VS Code settings or ~/.config/claude-code/config.json with the same format as above.

See Claude Code MCP documentation for platform-specific details.

HTTP/SSE Configuration (All AI Assistants)

For HTTP/SSE transport, first start the server:

Then configure your AI assistant to connect via URL:

Note: With HTTP transport, environment variables (SENZING_ENGINE_CONFIGURATION_JSON, etc.) must be set where the server runs, not in the AI assistant's config.

Other AI Assistants (ChatGPT, Amazon Q, etc.)

This MCP server works with any MCP-compatible assistant. The setup pattern is similar:

1. Locate your assistant's MCP config file:

   • ChatGPT Desktop: ~/Library/Application Support/ChatGPT/mcp_config.json (macOS)

   • Amazon Q Developer: VS Code settings → Amazon Q → MCP Servers

   • See official MCP documentation: https://modelcontextprotocol.io

2. Add server configuration with these key environment variables:

   { "mcpServers": { "senzing": { "command": "/path/to/senzing-mcp-server/launch_senzing_mcp.sh", "env": { "SENZING_ENGINE_CONFIGURATION_JSON": "{...}", "LD_LIBRARY_PATH": "/opt/senzing/lib", "PYTHONPATH": "/opt/senzing/sdk/python" } } } }

3. Restart your AI assistant to load the MCP server

Note: For SSH-based remote access, see the launch_senzing_mcp_ssh.sh script which includes configuration instructions in its comments.

Example Queries in Claude

Once configured, you can ask Claude natural language questions using any of the 7 read-only tools:

Entity Search & Retrieval

Relationship Analysis

Entity Resolution Explanations

Response Formatting Guide

For better interpretation of HOW and WHY analysis results, this repository includes a Response Formatting Guide (RESPONSE_FORMATTING.md) that helps AI assistants present entity resolution explanations in a clear, professional format.

What It Does

The formatting guide provides instructions for:

• HOW Analysis (explain_how_resolved): Step-by-step entity resolution explanations with merge steps and match drivers

• WHY Analysis (explain_why_related): Side-by-side entity comparisons showing confirmations and conflicts

How to Use with Your AI Assistant

The MCP server returns raw JSON data. To get nicely formatted explanations, provide the formatting guide to your AI assistant:

Option 1: Include in Conversation (All AI Assistants)

When asking about entity resolution, add:

Then paste the contents of RESPONSE_FORMATTING.md or provide it as an uploaded file.

Option 2: Add to Project Instructions (Claude Desktop/Projects)

1. Open your Claude project or conversation

2. Add RESPONSE_FORMATTING.md to project knowledge

3. Claude will automatically apply formatting rules to all HOW/WHY results

Option 3: Custom Instructions (ChatGPT/Other AI)

1. Copy the content from RESPONSE_FORMATTING.md

2. Add to your AI assistant's custom instructions or system prompt

3. The AI will automatically format Senzing results

Option 4: For Amazon Q Developer

1. Include RESPONSE_FORMATTING.md in your workspace

2. Reference it when asking about entity resolution:

   @workspace Please explain how entity 100 was resolved, using the formatting from RESPONSE_FORMATTING.md

Example: Before vs After Formatting

Without formatting guide:

With formatting guide:

See RESPONSE_FORMATTING.md for complete formatting examples and guidelines.

Architecture

Key Components

• server.py: MCP server implementation using the official mcp package

  • Defines 7 tools for entity resolution operations

  • Handles tool calls and routes to SDK wrapper

  • Supports both STDIO and HTTP/SSE transports (--http flag)

• sdk_wrapper.py: Async wrapper for synchronous Senzing SDK

  • Initializes SDK from environment variables

  • Provides async interface using ThreadPoolExecutor

  • Auto-reinitializes on stale config errors (SENZ2062)

  • Note: Requires Senzing environment to be initialized before import

Development

Running Tests

Debugging

Set log level for more verbose output:

Common Issues

SDK Initialization Failed

• Check that SENZING_ENGINE_CONFIGURATION_JSON is properly formatted

• Verify database connection settings

• Ensure Senzing resources are accessible at specified paths

Import Path Issues

• Verify LD_LIBRARY_PATH and PYTHONPATH are set correctly in your MCP config's env section

• Check that you can import senzing modules with environment variables set:

  LD_LIBRARY_PATH=/opt/senzing/lib PYTHONPATH=/opt/senzing/sdk/python \ python -c "import senzing"

License

This MCP server implementation is provided as-is. Senzing SDK usage is subject to Senzing licensing terms.

Support

For issues with:

• MCP Server: Check server logs and environment configuration

• Senzing SDK: Consult Senzing documentation

• Claude Integration: Verify MCP configuration in Claude Desktop settings