Troubleshooting

Claude doesn’t use the tools

Symptoms: Claude responds to clinical terminology questions with general knowledge instead of using the MCP tools.

Solutions:

1. Restart Claude Desktop after adding server configuration
2. Check the configuration file path is correct for your OS
3. Verify the binary path in your configuration exists and is executable
4. Look for errors in Claude’s MCP server logs

Check server is running:

# Test the binary directly
/path/to/bin/snomed-mcp
# Should output MCP initialization JSON

Authentication errors

ICD-11: “Unauthorized” or “Invalid credentials”

Symptoms: Error 401 when using ICD-11 tools.

Solutions:

1. Verify your credentials at icd.who.int/icdapi
2. Ensure environment variables are set correctly:

   "env": {
     "ICD11_CLIENT_ID": "your-id",
     "ICD11_CLIENT_SECRET": "your-secret"
   }
   

3. Check for extra whitespace in credentials
4. Regenerate credentials if they’ve expired

LOINC: “Authentication failed”

Symptoms: Error when using LOINC tools.

Solutions:

1. Use your LOINC.org account credentials (not a separate API key)
2. Verify login works at loinc.org
3. Check username/password in environment variables

UMLS: “Invalid API key”

Symptoms: Error when using UMLS tools.

Solutions:

1. Log in to uts.nlm.nih.gov
2. Go to Profile → API Key
3. Copy the current API key (they don’t expire but can be regenerated)
4. Ensure UMLS_API_KEY is set correctly

Connection errors

“Timeout” or “Connection refused”

Symptoms: Tools fail with network errors.

Solutions:

1. Check internet connectivity
2. Verify the API endpoint is reachable:

   curl https://snowstorm.ihtsdotools.org/snowstorm/snomed-ct/MAIN
   

3. Increase timeout if on slow connection:

   "env": {
     "HTTP_TIMEOUT": "60"
   }
   

4. Check if a firewall or proxy is blocking connections

“Certificate error” or “TLS handshake failed”

Symptoms: SSL/TLS errors when connecting to APIs.

Solutions:

1. Ensure system certificates are up to date
2. Check system time is correct (certificate validation requires accurate time)
3. Try updating the operating system

No results returned

SNOMED search returns empty

Possible causes:

1. Searching inactive concepts (add active_only: false if needed)
2. Wrong branch/edition configured
3. Search term too specific

Solutions:

1. Try broader search terms
2. Check branch configuration:

   "env": {
     "SNOWSTORM_BRANCH": "MAIN"  // or "MAIN/SNOMEDCT-US" for US edition
   }
   

RxNorm drug not found

Possible causes:

1. Brand name vs generic name
2. Drug not in RxNorm database
3. Spelling differences

Solutions:

1. Try both brand and generic names
2. Search for the active ingredient
3. Use partial matching (first few letters)

Debug logging

To see detailed MCP communication:

# Run server with verbose output
/path/to/bin/snomed-mcp 2>&1 | tee mcp-debug.log

Check the log for:

• Initialization messages
• Tool invocations
• API request/response details
• Error messages

Getting help

If you’re still having issues:

1. Check GitHub Issues for similar problems
2. Search existing discussions
3. Open a new issue with:
   • Server name and version
   • Operating system
   • Full error message
   • Steps to reproduce
   • Configuration (with credentials redacted)

Common error messages