AI Integration (MCP Server)

Digital ID includes a Model Context Protocol (MCP) server that allows AI assistants like Cursor or Claude Desktop to interact with your Digital ID system directly.

Overview

The MCP server acts as a bridge between AI assistants and your Digital ID database, allowing natural language queries and automated tasks:

• Employee Lookups: Find employee information by ID, email, or reference number
• ID Card Verification: Verify ID cards using QR codes or NFC tokens
• Log Analysis: Query verification logs with filtering options
• Employee Management: List employees, view pending photo approvals, and manage ID cards
• Organisation Data: Access organisation information and structure

How It Works

The MCP server is a TypeScript/Node.js application that:

1. Connects to Your Database: Uses MySQL connection to access Digital ID data securely
2. Exposes Tools: Provides standardised tools that AI assistants can call (like functions)
3. Communicates via JSON-RPC: Uses the Model Context Protocol standard over stdio (standard input/output)
4. Returns Structured Data: Formats database results as JSON for AI assistants to process

Available Tools

The MCP server provides the following tools that AI assistants can use:

Employee Management

Verification

Organisation

Available Resources

In addition to tools, the MCP server provides resources that AI assistants can read:

• digital-id://employees: List of all employees (limited to 1000 records)
• digital-id://organisations: List of all organisations

Setting Up the MCP Server

To use the MCP server with an AI assistant like Cursor or Claude Desktop, follow these steps:

Prerequisites

• Node.js 18+ installed on your system
• Access to the Digital ID database
• Database credentials (host, database name, username, password)
• An AI assistant that supports MCP (Cursor, Claude Desktop, etc.)

Step 1: Install Dependencies

1. Navigate to the MCP server directory:

   cd mcp-server

2. Install Node.js dependencies:

   npm install

Step 2: Configure Environment

1. Create a .env file in the mcp-server directory
2. Add your database credentials and organisation ID:

   DB_HOST=localhost
   DB_NAME=digital_ids
   DB_USER=your_db_user
   DB_PASS=your_db_password
   ORGANISATION_ID=1

3. Replace the values with your actual database credentials
4. Required: Set ORGANISATION_ID to the ID of the organisation whose data you want to access. The MCP server only supports organisation-wide access for security - all queries will be automatically filtered to this organisation.

Step 3: Build the Server

1. Compile the TypeScript code:

   npm run build

2. Verify the build succeeded - you should see a dist/index.js file

Step 4: Test the Server

1. Run the server to verify it works:

   npm start

2. You should see "Digital ID MCP Server running on stdio"
3. Press Ctrl+C to stop the server

Step 5: Configure Your AI Assistant

The configuration depends on which AI assistant you're using:

For Cursor

1. Open Cursor settings
2. Navigate to MCP settings (usually in Settings → Features → MCP)
3. Add the following configuration to your MCP settings file:

   {
     "mcpServers": {
       "digital-id": {
         "command": "node",
         "args": ["/absolute/path/to/digital-id/mcp-server/dist/index.js"],
         "env": {
           "DB_HOST": "localhost",
           "DB_NAME": "digital_ids",
           "DB_USER": "your_db_user",
           "DB_PASS": "your_db_password",
           "ORGANISATION_ID": "1"
         }
       }
     }
   }

4. Important: Replace /absolute/path/to/digital-id with the actual absolute path to your project directory
5. Replace database credentials with your actual values
6. Required: Add "ORGANISATION_ID": "1" with your organisation ID (replace 1 with your actual organisation ID). The MCP server requires this to be set.
7. Restart Cursor for changes to take effect

For Claude Desktop

1. Open Claude Desktop settings
2. Navigate to MCP settings (usually in Settings → Developer → MCP)
3. Add the same configuration as shown for Cursor above
4. Use the absolute path to dist/index.js
5. Restart Claude Desktop

Using the MCP Server

Once configured, you can interact with your Digital ID system using natural language in your AI assistant:

Example Queries

• "Get employee information for john.doe@example.com"
• "Show me verification logs for organisation ID 1 from last month"
• "List all employees with pending photo approvals"
• "Verify this ID card token: abc123..."
• "How many active employees are in organisation 2?"
• "Show me all failed verifications from yesterday"
• "Revoke the ID card for employee ID 5, reason: employee left"

Architecture

Understanding how the MCP server works helps with troubleshooting and customisation:

Communication Flow

1. AI Assistant: Receives user query in natural language
2. AI Assistant: Decides which MCP tool to call based on the query
3. MCP Server: Receives tool call request via JSON-RPC over stdio
4. MCP Server: Executes database query using provided parameters
5. MCP Server: Formats results as JSON
6. AI Assistant: Receives structured data and presents it to the user

Database Connection

The server maintains a single MySQL connection that is reused for all requests. The connection is created on first use and persists for the lifetime of the server process.

Error Handling

All errors are caught and returned in a standardised format that AI assistants can understand. Database errors, validation errors, and missing data are all handled gracefully.

Development Mode

For development, you can use watch mode to automatically rebuild when code changes:

npm run dev

This runs TypeScript compiler in watch mode, automatically recompiling when you save changes to src/index.ts.

Adding New Tools

To add custom functionality to the MCP server:

1. Add Tool Definition: Add a new tool object to the ListToolsRequestSchema handler in src/index.ts
   • Define the tool name, description, and input schema
   • Specify required and optional parameters
2. Implement Tool Handler: Add a case in the CallToolRequestSchema handler switch statement
   • Extract parameters from the request
   • Execute database queries
   • Return formatted JSON results
3. Rebuild: Run npm run build to compile changes
4. Restart: Restart your AI assistant to load the updated MCP server

Troubleshooting

Server Won't Start

• Check that Node.js 18+ is installed: node --version
• Verify database credentials in .env file
• Ensure the database server is running and accessible
• Check network connectivity if using a remote database

"Cannot Find Module" Errors

• Run npm install again to ensure dependencies are installed
• Verify you're in the mcp-server directory
• Check that dist/index.js exists after building
• Ensure node_modules directory exists

Database Connection Errors

• Verify database credentials are correct
• Check that the database server is running
• Ensure network access to the database (if remote)
• Verify database name, username, and password
• Check firewall settings if connecting remotely

Tools Not Appearing in AI Assistant

• Restart your AI assistant application completely
• Check the MCP configuration syntax is valid JSON
• Verify the path to dist/index.js is correct and absolute
• Check AI assistant logs for MCP connection errors
• Ensure the MCP server starts without errors when tested manually

Tools Return Errors

• Check database schema matches what the code expects
• Verify table names and column names are correct
• Check database user has necessary permissions
• Review error messages in AI assistant output for details

Security Considerations

Security Best Practices

To secure the MCP server, follow these recommendations:

1. Configure Organisation ID (Required): Set ORGANISATION_ID in your environment - this is mandatory
   • The MCP server requires ORGANISATION_ID to be set - it will not start without it
   • Automatically filters all queries to the specified organisation
   • Prevents access to other organisations' data
   • Essential for multi-tenant deployments
   • Example: Add ORGANISATION_ID=1 to your .env file
2. Use Read-Only Database Users: For production, create a read-only database user that can only SELECT data, not modify it
   • This prevents users from modifying data via the MCP server
   • They can still query all data, but cannot revoke cards or make changes
   • Example MySQL: GRANT SELECT ON digital_ids.* TO 'mcp_readonly'@'localhost';
3. Restrict Database Access: Only provide database credentials to trusted administrators
   • The MCP server is designed for administrators who already have database access
   • Do not share database credentials with end users
   • Use separate credentials for MCP server if possible
4. Protect Credentials: Never commit .env files or database credentials to version control
   • The .gitignore file excludes .env files
   • Use secure methods to share credentials (password managers, secure channels)
5. Network Security: The server runs locally via stdio (not HTTP), but still ensure network security
   • MCP servers communicate via stdio, so they're not directly accessible over the network
   • However, if database is remote, secure the database connection
   • Use SSH tunnels or VPNs for remote database access
6. Audit Access: Monitor who has access to database credentials
   • Keep records of who has database credentials
   • Review database access logs regularly
   • Rotate credentials periodically
7. Multi-Tenant Deployments: The MCP server is designed for organisation-wide access
   • ORGANISATION_ID is required - the server will not start without it
   • Each organisation must have its own MCP server instance with its own ORGANISATION_ID
   • This ensures complete isolation between organisations
   • No risk of cross-organisation data access

Benefits of MCP Integration

• Natural Language Queries: Ask questions about your Digital ID system in plain English
• Quick Data Access: Instantly retrieve employee information without navigating the web interface
• Automated Tasks: Perform routine administrative tasks through AI assistants
• Data Analysis: Query verification logs and analyse patterns using natural language
• Integration: Connect Digital ID data with other tools and workflows