IDmission Identity MCP Server

A Model Context Protocol (MCP) server that validates ID documents using the IDmission Identity API.

Purpose

This MCP server gives Claude a secure interface for submitting ID document images to IDmission's identity verification service and returning the verification result (e.g. Approved / Denied), without ever hardcoding credentials in code.

Features

Current Implementation

• validate_id - Submits front (and optionally back) images of an ID document to IDmission's validate-id endpoint, and returns the verification result, ID number, and expiration date

• validate_id_match_face - Submits the ID document image(s) plus a selfie to IDmission's validate-id-match-face endpoint, and returns whether the face match was approved

• live_check - Submits a selfie image to IDmission's live-check endpoint, and returns whether it was approved as a genuine live capture

These can be added later using the same authentication pattern already in place.

Prerequisites

• Docker Desktop with MCP Toolkit enabled

• Docker MCP CLI plugin (docker mcp command)

• IDmission API credentials: client ID, client secret, username, and password (contact your IDmission account team if you don't have these)

• A local folder containing the ID images you want to validate

Important: File Access

This server runs inside a Docker container, which cannot see files on your Mac/PC by default. To validate an ID image, you must mount a local folder containing your images into the container (e.g. map ~/idmission-images on your machine to /images inside the container). See the installation instructions for exactly where to configure this.

Once mounted, pass paths like /images/front.jpg (the container path, not your local path) to the validate_id tool.

Installation

See the step-by-step instructions provided alongside these files.

Usage Examples

In Claude Desktop, you can ask:

• "Validate this passport, front image at /images/passport_front.jpg, country GBR"

• "Run validate_id on /images/dl_front.jpg and /images/dl_back.jpg, id_type DL, id_country USA"

• "Validate /images/front.jpg with id_type NSP and id_country NSP" (lets IDmission auto-detect the document type and issuing country instead of specifying them)

• "Match the selfie at /images/selfie.jpg against the ID at /images/front.jpg, id_type NSP, id_country NSP"

• "Run a liveness check on /images/selfie.jpg"

Architecture

Claude Desktop → MCP Gateway → IDmission MCP Server → IDmission Auth (OAuth token)
                                                     → IDmission validate-id API
                        ↓
              Docker Desktop Secrets
    (IDMISSION_CLIENT_ID, IDMISSION_CLIENT_SECRET,
     IDMISSION_USERNAME, IDMISSION_PASSWORD, IDMISSION_SCOPE)

Development

Local Testing

# Set environment variables for testing
export IDMISSION_CLIENT_ID="your-client-id"
export IDMISSION_CLIENT_SECRET="your-client-secret"
export IDMISSION_USERNAME="your-username"
export IDMISSION_PASSWORD="your-password"

# Run directly
python idmission_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python idmission_server.py

Adding New Tools (e.g. live-check, validate-id-match-face)

1. Add a new async def function to idmission_server.py, reusing get_access_token() for auth

2. Decorate with @mcp.tool()

3. Use a single-line docstring and string parameter defaults (param: str = "")

4. Update the catalog entry's tools: list with the new tool name

5. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify the Docker image built successfully

• Check catalog and registry files

• Ensure Claude Desktop config includes the custom catalog

• Restart Claude Desktop

"Front ID image not found" errors

• Confirm the images folder is mounted into the container

• Use the container-side path (e.g. /images/front.jpg), not your local machine's path

Authentication Errors

• Verify secrets with docker mcp secret list

• Confirm the four required secrets are all set: IDMISSION_CLIENT_ID, IDMISSION_CLIENT_SECRET, IDMISSION_USERNAME, IDMISSION_PASSWORD

• IDmission uses the OAuth password grant — double-check the username/password are correct API credentials, not your portal login

Security Considerations

• All credentials stored in Docker Desktop secrets, never hardcoded

• Access tokens are cached in memory only, never logged or written to disk

• Running as a non-root user inside the container

• ID images are read into memory, base64-encoded, and sent directly to IDmission — never persisted by this server

• Sensitive data (tokens, passwords, image contents) never logged

License

MIT License