Configuration

Environment variables and configuration options for each MCP server.

Each MCP server can be configured through environment variables. Set these before starting the server or include them in your AI client’s MCP configuration.

Credential Storage

Servers requiring authentication (ICD-11, LOINC, UMLS) support two credential sources:

Environment variables (recommended for CI/automation)
System keyring (convenient for local development)

Environment variables always take precedence. If not set, the server checks the system keyring.

macOS (Keychain)

# Store credentials
security add-generic-password -s "clinical-terminology-mcp" -a "ICD11_CLIENT_ID" -w "your-client-id"
security add-generic-password -s "clinical-terminology-mcp" -a "ICD11_CLIENT_SECRET" -w "your-secret"
security add-generic-password -s "clinical-terminology-mcp" -a "LOINC_USERNAME" -w "your-username"
security add-generic-password -s "clinical-terminology-mcp" -a "LOINC_PASSWORD" -w "your-password"
security add-generic-password -s "clinical-terminology-mcp" -a "UMLS_API_KEY" -w "your-api-key"

# View stored credentials
security find-generic-password -s "clinical-terminology-mcp" -a "ICD11_CLIENT_ID" -w

# Delete a credential
security delete-generic-password -s "clinical-terminology-mcp" -a "ICD11_CLIENT_ID"

Linux (Secret Service / GNOME Keyring)

Requires libsecret-tools package (apt install libsecret-tools on Debian/Ubuntu).

# Store credentials
secret-tool store --label="ICD11_CLIENT_ID" service clinical-terminology-mcp account ICD11_CLIENT_ID
secret-tool store --label="ICD11_CLIENT_SECRET" service clinical-terminology-mcp account ICD11_CLIENT_SECRET
secret-tool store --label="UMLS_API_KEY" service clinical-terminology-mcp account UMLS_API_KEY

# Retrieve a credential
secret-tool lookup service clinical-terminology-mcp account ICD11_CLIENT_ID

# Clear a credential
secret-tool clear service clinical-terminology-mcp account ICD11_CLIENT_ID

Windows (Credential Manager)

# Store credentials
cmdkey /generic:"clinical-terminology-mcp:ICD11_CLIENT_ID" /user:"ICD11_CLIENT_ID" /pass:"your-client-id"
cmdkey /generic:"clinical-terminology-mcp:ICD11_CLIENT_SECRET" /user:"ICD11_CLIENT_SECRET" /pass:"your-secret"
cmdkey /generic:"clinical-terminology-mcp:UMLS_API_KEY" /user:"UMLS_API_KEY" /pass:"your-api-key"

# List stored credentials
cmdkey /list:clinical-terminology-mcp*

# Delete a credential
cmdkey /delete:"clinical-terminology-mcp:ICD11_CLIENT_ID"

HTTP Transport (Remote Mode)

All servers support running as HTTP services for remote deployment using the MCP Streamable HTTP transport.

Enabling HTTP Mode

# Via environment variable
MCP_TRANSPORT=http MCP_HTTP_ADDR=:8080 ./snomed-mcp

# Via CLI flags
./snomed-mcp --transport=http --http-addr=:8080

Transport Environment Variables

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`MCP_HTTP_ADDR`	`:8080`	HTTP listen address
`MCP_HTTP_PATH`	`/mcp`	MCP endpoint path
`MCP_TLS_CERT`		TLS certificate file
`MCP_TLS_KEY`		TLS private key file
`MCP_REQUEST_TIMEOUT`	`30`	Request timeout in seconds
`MCP_SHUTDOWN_TIMEOUT`	`30`	Graceful shutdown timeout in seconds
`MCP_STATELESS`	`false`	Disable session tracking for horizontal scaling

CLI Flags

All transport settings can also be set via CLI flags:

-transport string     Transport mode: stdio or http (default "stdio")
-http-addr string     HTTP listen address (default ":8080")
-http-path string     MCP endpoint path (default "/mcp")
-tls-cert string      TLS certificate file
-tls-key string       TLS private key file
-request-timeout int  Request timeout in seconds (default 30)
-shutdown-timeout int Shutdown timeout in seconds (default 30)
-stateless            Disable session tracking

Claude Code Remote Configuration

Connect Claude Code to a remote server:

{
  "mcpServers": {
    "snomed": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Health Endpoint

HTTP mode exposes a health endpoint at /health:

curl http://localhost:8080/health
# {"status":"ok"}

TLS Configuration

For production deployments, enable TLS:

MCP_TRANSPORT=http \
MCP_TLS_CERT=/path/to/cert.pem \
MCP_TLS_KEY=/path/to/key.pem \
./snomed-mcp

SNOMED CT (snomed-mcp)

# Snowstorm API endpoint (default: https://snowstorm.ihtsdotools.org/snowstorm/snomed-ct)
SNOWSTORM_URL=https://your-snowstorm-instance.com/snowstorm/snomed-ct

# SNOMED edition branch (default: MAIN)
SNOWSTORM_BRANCH=MAIN/SNOMEDCT-US

# Optional authentication
SNOWSTORM_AUTH_TYPE=basic  # or "bearer"
SNOWSTORM_AUTH_USERNAME=your-username
SNOWSTORM_AUTH_PASSWORD=your-password
SNOWSTORM_AUTH_TOKEN=your-bearer-token

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

Example with authentication

{
  "mcpServers": {
    "snomed": {
      "command": "/path/to/bin/snomed-mcp",
      "env": {
        "SNOWSTORM_URL": "https://your-snowstorm.com/snowstorm/snomed-ct",
        "SNOWSTORM_AUTH_TYPE": "basic",
        "SNOWSTORM_AUTH_USERNAME": "user",
        "SNOWSTORM_AUTH_PASSWORD": "pass"
      }
    }
  }
}

RxNorm (rxnorm-mcp)

# RxNorm API endpoint (default: https://rxnav.nlm.nih.gov/REST)
RXNORM_URL=https://rxnav.nlm.nih.gov/REST

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

No authentication required.

ICD-10 (icd10-mcp)

# Clinical Tables API endpoint (default: https://clinicaltables.nlm.nih.gov)
ICD10_URL=https://clinicaltables.nlm.nih.gov

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

No authentication required.

ICD-11 (icd11-mcp)

ICD-11 requires OAuth2 credentials from the WHO API portal.

# WHO ICD-11 API endpoint (default: https://id.who.int)
ICD11_URL=https://id.who.int

# Required: OAuth2 credentials from https://icd.who.int/icdapi
ICD11_CLIENT_ID=your-client-id
ICD11_CLIENT_SECRET=your-client-secret

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

Getting ICD-11 credentials

Register at icd.who.int/icdapi
Create an application to get client ID and secret
Set via environment variables or store in system keyring (see Credential Storage above)

LOINC (loinc-mcp)

LOINC uses FHIR terminology services with basic authentication.

# FHIR terminology server (default: https://fhir.loinc.org)
LOINC_URL=https://fhir.loinc.org

# Required: LOINC credentials from https://loinc.org
LOINC_USERNAME=your-username
LOINC_PASSWORD=your-password

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

Getting LOINC credentials

Register at loinc.org
Use your LOINC.org login credentials
Set via environment variables or store in system keyring (see Credential Storage above)

UMLS (umls-mcp)

UMLS requires an API key from the NLM.

# UMLS API endpoint (default: https://uts-ws.nlm.nih.gov/rest)
UMLS_URL=https://uts-ws.nlm.nih.gov/rest

# Required: API key from https://uts.nlm.nih.gov/uts/
UMLS_API_KEY=your-api-key

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

Getting a UMLS API key

Create an account at uts.nlm.nih.gov
Sign the UMLS license agreement
Generate an API key from your profile
Set via environment variable or store in system keyring (see Credential Storage above)

UCUM (ucum-mcp)

# UCUM API endpoint (default: https://clinicaltables.nlm.nih.gov)
UCUM_URL=https://clinicaltables.nlm.nih.gov

# HTTP timeout in seconds (default: 30)
HTTP_TIMEOUT=30

No authentication required.

Client Setup

For step-by-step instructions on configuring these servers in your AI client, see the Client Setup guides:

Claude Desktop — JSON config
Claude Code — CLI commands
VS Code / GitHub Copilot — settings.json
Cursor — mcp.json
Windsurf — mcp_config.json
OpenAI Codex — config.toml + Desktop GUI

Tips

Start with servers that don’t require authentication (snomed, rxnorm, icd10, ucum)
Add authenticated services as needed for your use case
Use the public Snowstorm server for testing; run your own for production
Set appropriate HTTP timeouts for your network conditions
Use system keyring for local development to avoid credentials in config files
Use environment variables for CI/CD pipelines and containerized deployments