Skip to main content
search

Quickstart Guide

Senzing V4 SDK
AWS AI Assistant Extension
(Amazon Q)

This guide shows you how to enable AI assistant integration with Senzing using Amazon Q Developer and the Model Context Protocol (MCP)โ€”an open standard that allows AI assistants to interact with Senzing’s entity resolution capabilities through natural language.

What you’ll be able to do:

  • Map data with AI guidance – Transform CSV, JSON, or database records into Senzing format with intelligent suggestions
  • Explore entities naturally – Ask “Show me all entities related to this person” or “Why were these records merged?”
  • Understand resolution decisions – Get detailed explanations of how Senzing resolved entities
  • Validate mappings – AI understands Senzing semantics and catches errors before loading

Amazon Q Developer

New to Amazon Q? Read the Amazon Q Developer documentation first. This guide uses the IDE Plugin pattern with Amazon Q as the reference implementation. The MCP Server is compatible with any IDE that supports the Model Context Protocol and any language model provider. All development tools run on your LOCAL workstation, not on the EC2 instance.

Data Privacy & Security

  • No customer data storage: Amazon Q and the MCP Server do not store, log, or persist your entity resolution data. All queries are processed in real-time and discarded after response.
  • SSH tunnel encryption: All communication between your workstation and EC2 instance uses SSH encryption (AES-256), ensuring data in transit is protected.
  • Data sovereignty: Your Senzing data remains in your AWS VPC. Amazon Q only receives query results you explicitly request through the MCP protocol.

Senzingยฎ Smarter Entity Resolutionโ„ข SDK with Entity Centric Learningโ„ข technology. Connect Data. Power Intelligence.โ„ข entity resolution.

Amazon Q + Senzing Architecture

Architecture Overview

Amazon Q’s Role: Your AI pair programmer helping you write mapping code AND your database analyst for querying

Architecture Diagram
The following diagram uses official AWS Architecture Icons to illustrate component placement and data flow. Shows developer workstation, AWS VPC components, and security group boundaries.

Amazon q quickstart ai data mapping and ai querying

Prerequisites

Steps 1 & 2:

This extension guide assumes you have completed Steps 1 and 2 in the Senzing V4 SDK AWS Quickstart Guide. For universal deployment options (Azure, GCP, Docker, homelab), see the cloud-agnostic SENZING_MCP_QUICKSTART.html

Steps 3 โ€“ 6: (Optional)

There are also OPTIONAL PostgreSQL setup Steps 3-6 in the base AWS quickstart for production deployments with concurrent AI queries. SQLite works for single-user development and testing.

Before extending your Senzing deployment with Amazon Q, ensure you have:

  • AWS Account with administrative privileges
  • AWS Builder ID for Amazon Q access (register here)
  • SSH key pair for EC2 access
  • Local workstation with compatible IDE installed, OR access to AWS Console

Key Points:

  • mapper-ai tools run on your LOCAL laptop – pure Python, no Senzing SDK needed
  • Amazon Q helps write mapping code in your IDE
  • Generated JSONL files transferred to EC2 for loading
  • Two separate security groups for defense-in-depth

Security Architecture

  • SSH Tunnel Encryption: All MCP protocol communication uses AES-256 encryption via SSH
  • Database Isolation: RDS security group (rds-sg) ONLY allows PostgreSQL :5432 FROM senzing-sg (not from internet, not from other security groups)
  • No Public Database Access: PostgreSQL port 5432 is not exposed to the internet under any circumstances
  • Key-Based Authentication: SSH access requires private key, no password authentication
  • Principle of Least Privilege: EC2 security group (senzing-sg) only allows outbound to RDS, RDS only allows inbound from EC2

Info

Senzing provides a free license for 500 source records when downloading the Senzingยฎ SDK. If you require additional records for an evaluation, or any assistance when following this guide, contact Senzing Support. Support is 100% FREE!

Amazon Q Extension Instructions

Estimated Time: Steps 7-10 take approximately 20-30 minutes (10 min EC2 setup + 10 min local IDE setup + 5-10 min configuration and testing)

Step 7: Install mapper-ai Tools on Your LOCAL Workstation

Step 7 Time: 2-3 minutes

Info: Complete mapper-ai usage guide and 5-stage AI workflow: github.com/senzing/mapper-ai

Important: mapper-ai tools run on YOUR laptop, NOT on the EC2 instance. These are pure Python tools that don’t require Senzing SDK.

1.  On your LOCAL workstation (laptop), clone the mapper-ai repository:

cd ~/projects # or your preferred directory
git clone https://github.com/senzing/mapper-ai.git
cd mapper-ai

2. Verify installation:

python3 senzing/tools/sz_schema_generator.py –help

3. Test with sample data (optional):

python3 senzing/tools/sz_schema_generator.py your_data.csv -o schema.md

Step 8: Install Senzing MCP Server on EC2 Instance

Step 8 Time: 5-7 minutes

Info: If you completed PostgreSQL setup (Steps 3-6), update the CONNECTION string:
“CONNECTION”: “postgresql://senzing:password@YOUR-RDS-ENDPOINT:5432/G2”

Complete MCP Server configuration and tool reference: github.com/jbutcher21/senzing-mcp-server

 

Important
The MCP Server runs on the EC2 instance where Senzing SDK is installed, NOT on your local workstation.

1. SSH into your EC2 instance:

ssh -i /path/to/your-key.pem ec2-user@YOUR-EC2-IP

2. Install the MCP server on the EC2 instance:

cd ~
git clone https://github.com/jbutcher21/senzing-mcp-server.git
cd senzing-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure environment (if using SQLite – default from base quickstart):

export SENZING_ENGINE_CONFIGURATION_JSON='{
“PIPELINE”: {
    “CONFIGPATH”: “/etc/opt/senzing”,
    “RESOURCEPATH”: “/opt/senzing/g2/resources”,
    “SUPPORTPATH”: “/opt/senzing/data”
  },
  “SQL”: {
    “CONNECTION”: “sqlite3://na:na@/var/opt/senzing/sqlite/G2C.db”
  }
}’

4. Test the MCP server:

python src/senzing_mcp/server.py

You should see JSON-RPC server output. Press Ctrl+C to exit.

Step 9: Install AI Assistant Client

Step 9 Time: 3-5 minutes

Important: Choose ONE of the following access patterns. This guide uses Amazon Q as the reference implementation, but the architecture supports any MCP-compatible client.

Option A: IDE Plugin (Local Development)

Install an AI assistant extension in your local IDE:

  1. Open your IDE on your local workstation
  2. Navigate to the extensions/plugins marketplace
  3. Search for and install the AWS AI assistant extension
  4. Sign in with your AWS Builder ID

Info
For Amazon Q: Available in the marketplace for most popular IDEs. Check AWS documentation for supported IDEs and installation instructions.

Option B: AWS Console (Web Browser)

Access AI assistant directly through AWS Console:

  1. Navigate to AWS Console
  2. Sign in with your AWS account
  3. Open Amazon Q from the console toolbar (icon in top navigation)
  4. Configure MCP connection through console settings

Note
AWS Console access provides browser-based interaction with the same MCP Server capabilities. No local IDE installation required.

Step 10: Configure MCP Connection

Step 10 Time: 5-8 minutes

Important: This configuration file is created on YOUR local workstation, not on the EC2 instance. The configuration format may vary depending on your IDE plugin and language model provider.

Connection Security: The SSH tunnel uses AES-256 encryption for all data in transit. Your SSH key must have restricted permissions (chmod 400 on macOS/Linux).

1. On your LOCAL workstation, create the MCP configuration directory:

# macOS/Linux
mkdir -p ~/.aws/amazonq

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.aws\amazonq

2. Create MCP configuration file ~/.aws/amazonq/mcp.json on your workstation:

{
“mcpServers”: {
“senzing”: {
“command”: “ssh”,
“args”: [
“-i”, “/path/to/your-key.pem”,
“ec2-user@YOUR-EC2-IP”,
“cd senzing-mcp-server && source venv/bin/activate && python src/senzing_mcp/server.py”
],
“env”: {
“SENZING_ENGINE_CONFIGURATION_JSON”: “{\”PIPELINE\”:{\”CONFIGPATH\”:\”/etc/opt/senzing\”,\”RESOURCEPATH\”:\”/opt/senzing/g2/resources\”,\”SUPPORTPATH\”:\”/opt/senzing/data\”},\”SQL\”:{\”CONNECTION\”:\”sqlite3://na:na@/var/opt/senzing/sqlite/G2C.db\”}}”
}
}
}
}

3. Replace /path/to/your-key.pem with your actual SSH key path

4. Replace YOUR-EC2-IP with your EC2 instance’s public IP address

5. If using PostgreSQL, update the CONNECTION string in env section

6. Restart your IDE to activate the MCP connection

Health Checks & Troubleshooting

Verify Installation

1.  Test MCP Server Connection:

  • In your IDE, open Amazon Q chat
  • Ask: What Senzing tools are available?
  • Expected response should list 7 tools: search_entities, get_entity, get_source_record, find_path, expand_network, explain_why_related, explain_how_resolved

2. Test Entity Query:

Ask Amazon Q: “Search for entities with name ‘Robert Smith'”

Expected: If you loaded the truth set data (from base quickstart), Amazon Q should return entity results.

3. Verify SSH Tunnel:

# On your workstation
ssh -i /path/to/your-key.pem ec2-user@YOUR-EC2-IP “echo ‘SSH connection working'”

Expected: SSH connection working

Common Issues & Solutions

Issue: “MCP Server not responding”

  • Check: EC2 security group allows SSH (port 22) from your IP
  • Check: SSH key permissions are correct (chmod 400)
  • Test: SSH directly to EC2 and run MCP server manually
  • Solution: Verify SENZING_ENGINE_CONFIGURATION_JSON is set correctly

Issue: “No entities found”

  • Check: Truth set data was loaded (from base quickstart Step 2)
  • Check: Database path in configuration is correct
  • Test: SSH to EC2 and run: source ~/.bashrc && sz_explorer
  • Solution: Reload truth set data following base quickstart instructions

Issue: “Permission denied (publickey)”

  • Check: SSH key path in mcp.json is correct and absolute
  • Check: SSH key file has correct permissions (chmod 400)
  • Check: Using correct EC2 user (ec2-user for Amazon Linux)
  • Solution: Test SSH connection manually first before trying MCP

Issue: “Database connection failed”

  • Check: If using PostgreSQL, RDS security group allows 5432 from EC2
  • Check: CONNECTION string matches your database setup (SQLite or PostgreSQL)
  • Test: SSH to EC2 and test connection: psql -h YOUR-RDS-ENDPOINT -U senzing -d G2
  • Solution: Verify RDS endpoint and credentials are correct

Diagnostic Commands

On EC2 Instance (via SSH):

# Check Senzing environment
source ~/.bashrc
sz_explorer –version

# Test database connection (SQLite)
ls -la /var/opt/senzing/sqlite/G2C.db

# Test database connection (PostgreSQL)
psql -h YOUR-RDS-ENDPOINT -U senzing -d G2 -c “SELECT COUNT(*) FROM DSRC_RECORD;”

# Test MCP server manually
cd ~/senzing-mcp-server
source venv/bin/activate
python src/senzing_mcp/server.py
# Press Ctrl+C after seeing JSON-RPC output

On Local Workstation:

# Verify mapper-ai tools
cd ~/projects/mapper-ai
python3 senzing/tools/sz_schema_generator.py –help

# Test SSH connection
ssh -i /path/to/your-key.pem ec2-user@YOUR-EC2-IP “pwd”

# Check MCP configuration
cat ~/.aws/amazonq/mcp.json

Using Amazon Q with Senzing

AI-Assisted Data Mapping (Story 1)

Use mapper-ai tools on your LOCAL workstation with Amazon Q to generate Senzing mappers from your source data:

1. Analyze your source data:

cd ~/projects/mapper-ai
python3 senzing/tools/sz_schema_generator.py your_data.csv -o schema.md

2. Open mapper-ai repository in your IDE

3. In Amazon Q chat, share the schema:

    • Upload schema.md to the chat
    • Ask: “Help me create a Senzing mapper for this data”
    • Follow the 5-stage AI workflow in senzing/prompts/senzing_mapping_assistant.md

4. Generate mapper code: Amazon Q will create Python mapper code

5. Run mapper locally:

python3 your_mapper.py your_data.csv -o output.jsonl

6. Validate before loading:

python3 senzing/tools/sz_json_analyzer.py output.jsonl -o analysis.md

7. Transfer to EC2 and load:

scp -i /path/to/your-key.pem output.jsonl ec2-user@YOUR-EC2-IP:/tmp/
ssh -i /path/to/your-key.pem ec2-user@YOUR-EC2-IP
source ~/.bashrc && sz_file_loader -f /tmp/output.jsonl

Info
Complete AI-assisted mapping workflow and examples: mapper-ai documentation

AI-Powered Entity Querying (Story 2)

With Amazon Q connected to the MCP Server (via SSH tunnel), use natural language to query your Senzing deployment:

Example Queries:

  • “Search for entities named John Smith”
  • “Show me entity 1234”
  • “Get relationships for entity ID 123”
  • “Why did entities 100 and 200 resolve together?”
  • “How was entity 50 constructed?”
  • “Find the path between entity 10 and entity 20”

Data Privacy Reminder
Amazon Q and the MCP Server do not store your query results or entity data. All queries are processed in real-time and discarded after response. Your Senzing data remains in your AWS VPC.

Info
Complete MCP tool reference and query examples: senzing-mcp-server documentation

Component Deployment Summary

Component Deployment Location Purpose Access Method
mapper-ai tools Developer Laptop Generate Senzing JSONL from CSV/JSON Local file system
Amazon Q IDE Plugin Developer Laptop MCP client, SSH tunnel manager Installed in IDE
Amazon Q Service (LLM) โ˜๏ธ AWS Bedrock AI language model HTTPS API
MCP Server โ˜๏ธ EC2 Instance Query interface to Senzing SDK SSH tunnel
Senzing SDK โ˜๏ธ EC2 Instance Entity resolution engine Local on EC2
PostgreSQL/SQLite โ˜๏ธ RDS Instance / EC2 file Entity database Port 5432 (RDS) or file (SQLite)
Close Menu