Using SmartEM MCP Interface#

The SmartEM MCP (Model Context Protocol) interface provides natural language querying capabilities for microscopy session data. Built with FastMCP 2.0, it supports both filesystem-based parsing and API-based queries for comprehensive data access.

Overview#

The MCP interface consists of:

FastMCP Server: Provides natural language query capabilities via MCP protocol using FastMCP framework
MCP Client: Python client for programmatic access with simplified FastMCP patterns
CLI Interface: Command-line tools for interactive usage

Installation#

Install with MCP dependencies (includes FastMCP 2.0 framework):

pip install -e .[mcp]

This installs the required FastMCP 2.0 framework and SmartEM MCP components.

Quick Start#

1. Interactive Query Mode#

Start interactive mode for natural language questions:

python -m smartem_mcp interactive

Example questions:

“Show me a summary of session /path/to/epu/directory”
“Find low quality items in /path/to/epu with threshold 0.3”
“What are the recent acquisitions?”

2. Command Line Usage#

Parse EPU directory:

python -m smartem_mcp client parse --path /path/to/epu/session

Find low quality items:

python -m smartem_mcp client quality --path /path/to/epu --threshold 0.3

Query recent acquisitions (requires API):

python -m smartem_mcp client acquisitions --limit 10

3. Programmatic Usage#

from smartem_mcp.client import SmartEMMCPClient

async with SmartEMMCPClient() as client:
    # Parse EPU directory
    result = await client.parse_epu_directory("/path/to/epu")
    if result.get("success"):
        print(f"Found {result['grid_count']} grids")
    
    # Find low quality items
    quality_result = await client.find_low_quality_items(
        "/path/to/epu", 
        threshold=0.3
    )
    
    # Query API data
    acquisitions = await client.query_recent_acquisitions(limit=5)

Data Sources#

Filesystem Queries#

Direct parsing of EPU XML files using existing smartem_agent tools:

Use case: Ad-hoc analysis, debugging, development
Capabilities: Full EPU directory parsing, quality analysis
Requirements: Direct filesystem access to EPU data

API Queries#

Query historical and in-flight sessions via SmartEM API:

Use case: Historical analysis, live session monitoring
Capabilities: Acquisition status, grid processing, real-time data
Requirements: Running SmartEM backend service

Claude Code Integration#

The SmartEM MCP server integrates seamlessly with Claude Code, allowing natural language queries about microscopy data directly within your development environment.

Prerequisites#

Ensure MCP dependencies are installed (includes FastMCP 2.0):

pip install -e .[mcp]

Verify the installation:

python -m smartem_mcp --version

Registration with Claude Code#

Option 1: Using Claude CLI (Recommended)#

Register the SmartEM MCP server using the Claude CLI:

# Basic registration (user-wide scope)
claude mcp add smartem -- python -m smartem_mcp server

# With custom API URL
claude mcp add smartem -- python -m smartem_mcp server --api-url http://localhost:30080

# Project-scoped registration
claude mcp add smartem --scope project -- python -m smartem_mcp server --api-url http://localhost:30080

Option 2: Manual Configuration#

If you prefer manual configuration, add the server to your Claude Code settings:

For user-wide registration: Edit ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "smartem": {
      "command": "python",
      "args": ["-m", "smartem_mcp", "server", "--api-url", "http://localhost:30080"],
      "env": {
        "SMARTEM_API_URL": "http://localhost:30080",
        "SMARTEM_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

For project-scoped registration: Create .claude/mcp.json in your project root:

{
  "mcpServers": {
    "smartem": {
      "command": "python",
      "args": ["-m", "smartem_mcp", "server"],
      "env": {
        "SMARTEM_API_URL": "http://localhost:30080"
      }
    }
  }
}

Registration Options#

Environment Variables#

Configure the MCP server behaviour through environment variables:

SMARTEM_API_URL: Base URL for SmartEM API (default: http://localhost:30080)
SMARTEM_MCP_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
PYTHON_PATH: Python executable path if not in system PATH

Example with custom environment:

claude mcp add smartem --env SMARTEM_API_URL=http://production.server:8080 --env SMARTEM_MCP_LOG_LEVEL=DEBUG -- python -m smartem_mcp server

Scope Options#

User scope (default): Available across all Claude Code projects
Project scope: Only available within the current project directory

# User-wide (default)
claude mcp add smartem -- python -m smartem_mcp server

# Project-specific
claude mcp add smartem --scope project -- python -m smartem_mcp server

Verification#

1. Check Registration Status#

# List all registered MCP servers
claude mcp list

# Check SmartEM server status
claude mcp status smartem

2. Test Connection#

Start a new Claude Code session and verify the SmartEM tools are available:

# In Claude Code, type a natural language query:
# "List all available SmartEM tools"

You should see the following tools available:

parse_epu_directory - Parse EPU microscopy directories
query_quality_metrics - Find low-quality images and foil holes
query_acquisitions - Query recent acquisition sessions
query_grid_status - Get grid processing status

Note: The client provides high-level methods such as find_low_quality_items() which internally call the corresponding MCP tools.

3. Test Basic Functionality#

Try a simple query in Claude Code:

“Parse the EPU directory at /path/to/your/epu/session”

Usage in Claude Code#

Once registered, you can interact with SmartEM data using natural language within Claude Code:

Directory Analysis#

“Show me a comprehensive analysis of the EPU session at /data/microscopy/session_001”

“What grids and grid squares are available in /path/to/epu/directory?”

Quality Assessment#

“Find all images with quality scores below 0.4 in the EPU directory /data/session_001”

“Show me foil holes that need attention from /path/to/epu with quality threshold 0.3”

Session Monitoring#

“What are the 5 most recent microscopy acquisitions?”

“Check the processing status of grid uuid-12345”

Advanced Queries#

“Compare quality metrics between /data/session_001 and /data/session_002”

“Generate a report for all low-quality items found today”

Server Mode (Standalone)#

For advanced users or debugging, run the MCP server in standalone mode:

python -m smartem_mcp server --api-url http://localhost:30080 --log-level DEBUG

This starts the server with stdio communication, primarily useful for:

Debugging MCP protocol issues
Custom client integrations
Development and testing

Available Tools#

`parse_epu_directory`#

Parse EPU microscopy directory and extract comprehensive session data.

Parameters:

path (required): Path to EPU output directory containing EpuSession.dm

Returns: Acquisition data, grids, grid squares, and statistics

`query_quality_metrics`#

Find foil holes and micrographs with quality scores below threshold.

Parameters:

path (required): Path to EPU directory
threshold (optional): Quality threshold (default: 0.5)
source (optional): “filesystem” or “api” (default: filesystem)

Returns: List of low-quality items with metadata

`query_acquisitions`#

Query recent microscopy acquisition sessions from API.

Parameters:

limit (optional): Number of acquisitions to return (default: 10)

Returns: List of acquisitions with status and metadata

`query_grid_status`#

Get detailed status and processing state for specific grid.

Parameters:

grid_id (required): Grid UUID or identifier

Returns: Grid details and processing status

Future Enhancements#

The following capabilities are scaffolded for future implementation:

Real-time Event Streaming#

# Future capability - real-time updates via RabbitMQ
events = await client.subscribe_to_events("acquisition.*.quality_updated")

Direct Database Querying#

# Future capability - direct read-only database access
result = await client.query_database("SELECT * FROM micrographs WHERE quality < 0.3")

Error Handling#

All operations return structured results with success indicators:

result = await client.parse_epu_directory("/path/to/epu")
if result.get("success"):
    # Process result data
    data = result.get("data", {})
    pass
else:
    print(f"Error: {result.get('error')}")

Configuration#

Environment Variables#

SMARTEM_API_URL: Base URL for SmartEM API (default: http://localhost:30080)
SMARTEM_MCP_LOG_LEVEL: Logging level (default: INFO)

API Authentication#

For authenticated API access (future):

client = SmartEMMCPClient(api_token="your_token_here")

Troubleshooting#

Common Issues#

1. MCP Server Registration Problems#

“SmartEM MCP server not found”

Ensure MCP dependencies are installed: pip install -e .[mcp] (includes FastMCP 2.0)
Verify Python path includes smartem_mcp module: python -c "import smartem_mcp; print('OK')"
Check registration with claude mcp list

“Failed to start MCP server”

Verify Python executable is accessible: which python
Test server manually: python -m smartem_mcp server --api-url http://localhost:30080
Check environment variables are properly set

“MCP server registered but not responding”

Remove and re-add the server: claude mcp remove smartem && claude mcp add smartem -- python -m smartem_mcp server
Restart Claude Code completely
Check server logs: claude mcp logs smartem

2. Directory and Data Issues#

“Invalid EPU directory”

Verify directory contains EpuSession.dm file
Check Metadata/ and Images-Disc*/ subdirectories exist
Ensure proper file permissions for reading EPU data

“Permission denied accessing EPU files”

Check file permissions: ls -la /path/to/epu/directory
Ensure user has read access to all EPU subdirectories
For network mounts, verify mount permissions

3. API Connection Issues#

“API connection failed”

Verify SmartEM backend is running: curl http://localhost:30080/health
Check API URL is correct in registration command
Test network connectivity to API endpoint

“Authentication failed” (Future feature)

Verify API tokens are properly configured
Check token expiration and renewal

4. Claude Code Integration Issues#

“Tools not available in Claude Code”

Restart Claude Code after registration
Check MCP server status: claude mcp status smartem
Verify registration scope (user vs project)

“Queries return empty results”

Test with standalone client: python -m smartem_mcp client parse --path /path/to/epu
Check EPU directory structure and data validity
Verify API connectivity for acquisition queries

Debug Mode#

Enable Debug Logging#

For MCP server debugging:

claude mcp add smartem --env SMARTEM_MCP_LOG_LEVEL=DEBUG -- python -m smartem_mcp server --api-url http://localhost:30080 --log-level DEBUG

For client debugging:

python -m smartem_mcp --log-level DEBUG client parse --path /path/to/epu

Check Server Logs#

View MCP server logs in Claude Code:

claude mcp logs smartem

Manual Server Testing#

Test the server independently of Claude Code:

# Start server in stdio mode for testing
python -m smartem_mcp server --log-level DEBUG

# The server uses FastMCP stdio communication protocol
# For testing, use interactive mode or programmatic client instead:
python -m smartem_mcp interactive

Environment-Specific Troubleshooting#

Development Environment#

Ensure virtual environment is activated when registering
Use absolute Python paths: claude mcp add smartem -- /path/to/.venv/bin/python -m smartem_mcp server

Production Environment#

Verify all dependencies are installed in production Python environment
Check firewall rules for API connectivity
Ensure proper logging configuration for production

Container Environments#

Mount EPU directories properly in container
Expose API ports correctly
Set environment variables in container runtime

Getting Help#

If issues persist:

Gather diagnostic information:

# System info
python --version
pip list | grep -E "(smartem|mcp)"
claude mcp list
claude mcp status smartem

# Test basic functionality
python -m smartem_mcp --version
python -c "import smartem_mcp; print('Import successful')"

Check project documentation: SmartEM Decisions README
Review MCP protocol documentation: Model Context Protocol Specification
Submit issue: Include diagnostic information and specific error messages

Integration with Claude Code#

When properly configured, you can ask Claude Code natural language questions:

“Show me all grid squares with quality scores below 0.5 from the EPU session at /data/session1”

“What’s the current status of acquisition abc-123?”

“List micrographs acquired in the last hour with defocus values”

The MCP server will automatically route these queries to the appropriate data sources and return formatted results.

Using SmartEM MCP Interface#

Overview#

Installation#

Quick Start#

1. Interactive Query Mode#

2. Command Line Usage#

3. Programmatic Usage#

Data Sources#

Filesystem Queries#

API Queries#

Claude Code Integration#

Prerequisites#

Registration with Claude Code#

Option 1: Using Claude CLI (Recommended)#

Option 2: Manual Configuration#

Registration Options#

Environment Variables#

Scope Options#

Verification#

1. Check Registration Status#

2. Test Connection#

3. Test Basic Functionality#

Usage in Claude Code#

Directory Analysis#

Quality Assessment#

Session Monitoring#

Advanced Queries#

Server Mode (Standalone)#

Available Tools#

parse_epu_directory#

query_quality_metrics#

query_acquisitions#

query_grid_status#

Future Enhancements#

Real-time Event Streaming#

Direct Database Querying#

Error Handling#

Configuration#

Environment Variables#

API Authentication#

Troubleshooting#

Common Issues#

1. MCP Server Registration Problems#

2. Directory and Data Issues#

3. API Connection Issues#

4. Claude Code Integration Issues#

Debug Mode#

Enable Debug Logging#

Check Server Logs#

Manual Server Testing#

Environment-Specific Troubleshooting#

Development Environment#

Production Environment#

Container Environments#

Getting Help#

Integration with Claude Code#

This Page

`parse_epu_directory`#

`query_quality_metrics`#

`query_acquisitions`#

`query_grid_status`#