Export/Import Quick Reference¶

Quick reference for MCP Gateway configuration export and import commands.

🚀 CLI Commands¶

Export Commands¶

# Complete backup
mcpgateway export --out backup.json

# Production tools only
mcpgateway export --types tools --tags production --out prod-tools.json

# Everything except metrics
mcpgateway export --exclude-types metrics --out config.json

# Include inactive entities
mcpgateway export --include-inactive --out complete.json

# Minimal export (no dependencies)
mcpgateway export --no-dependencies --out minimal.json

Import Commands¶

# Standard import
mcpgateway import backup.json

# Dry-run validation
mcpgateway import backup.json --dry-run

# Skip conflicts
mcpgateway import backup.json --conflict-strategy skip

# Cross-environment with key rotation
mcpgateway import backup.json --rekey-secret $NEW_SECRET

# Selective import
mcpgateway import backup.json --include "tools:api_tool;servers:ai_server"

🌐 API Endpoints¶

Export APIs¶

# GET /export - Full export with filters
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:4444/export?types=tools,gateways&include_inactive=true"

# POST /export/selective - Export specific entities
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"tools": ["tool1"], "servers": ["server1"]}' \
  "http://localhost:4444/export/selective"

Import APIs¶

# POST /import - Import configuration
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"import_data": {...}, "conflict_strategy": "update"}' \
  "http://localhost:4444/import"

# GET /import/status/{id} - Check import progress
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:4444/import/status/import-123"

# GET /import/status - List all imports
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:4444/import/status"

⚙️ Configuration¶

Required Environment Variables¶

# Authentication (choose one)
MCPGATEWAY_BEARER_TOKEN=your-jwt-token
# OR
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=your-password

# Encryption key for auth data
AUTH_ENCRYPTION_SECRET=your-32-char-secret

# Gateway connection
HOST=localhost
PORT=4444

Optional Settings¶

# Enable Admin UI for web-based export/import
MCPGATEWAY_UI_ENABLED=true
MCPGATEWAY_ADMIN_API_ENABLED=true

# Import limits and timeouts
MCPGATEWAY_BULK_IMPORT_MAX_TOOLS=200
MCPGATEWAY_BULK_IMPORT_RATE_LIMIT=10

🎭 Conflict Resolution¶

Strategy	Behavior	Use Case
`skip`	Skip existing entities	Additive imports
`update`	Overwrite existing entities	Environment promotion
`rename`	Add timestamp suffix	Preserve both versions
`fail`	Stop on conflicts	Strict validation

📊 Entity Types¶

Type	Identifier	Description
`tools`	`name`	REST API tools and MCP integrations
`gateways`	`name`	Peer gateway connections
`servers`	`name`	Virtual server compositions
`prompts`	`name`	Template definitions with schemas
`resources`	`uri`	Static and dynamic resources
`roots`	`uri`	Filesystem and HTTP root paths

🔍 Filtering Examples¶

By Entity Type¶

# Tools and gateways only
mcpgateway export --types tools,gateways

# Everything except servers
mcpgateway export --exclude-types servers,metrics

By Tags¶

# Production-tagged entities
mcpgateway export --tags production

# Multiple tags (OR condition)
mcpgateway export --tags api,data,production

By Status¶

# Active entities only (default)
mcpgateway export

# Include inactive entities
mcpgateway export --include-inactive

Selective Import¶

# Specific tools and servers
mcpgateway import backup.json --include "tools:weather_api,translate;servers:ai_server"

# Single entity type
mcpgateway import backup.json --include "tools:*"

🔧 Troubleshooting Quick Fixes¶

"Authentication Error"¶

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 0 --secret my-test-key)

"Gateway Connection Failed"¶

# Check gateway is running
curl http://localhost:4444/health

# Verify port and host
netstat -tlnp | grep 4444

"Invalid Export Format"¶

# Validate JSON structure
jq empty export.json

# Check required fields
jq 'has("version") and has("entities")' export.json

"Encryption/Decryption Failed"¶

# Ensure consistent encryption key
echo $AUTH_ENCRYPTION_SECRET

# Use same key for export and import environments
mcpgateway import backup.json --rekey-secret $AUTH_ENCRYPTION_SECRET

📋 Common Workflows¶

Daily Backup¶

#!/bin/bash
DATE=$(date +%F)
mcpgateway export --out "backup-$DATE.json"
echo "✅ Backup created: backup-$DATE.json"

Environment Sync¶

#!/bin/bash
# Sync staging to production
mcpgateway export --tags production --out staging-config.json
mcpgateway import staging-config.json --rekey-secret $PROD_SECRET --dry-run
mcpgateway import staging-config.json --rekey-secret $PROD_SECRET

Selective Migration¶

#!/bin/bash
# Migrate specific tools between environments
mcpgateway export --types tools --tags migrate --out tools-migration.json
mcpgateway import tools-migration.json --include "tools:*" --conflict-strategy update