Configuration

This guide covers all configuration options for MCP Composer.

Overview

MCP Composer uses multiple configuration files and environment variables to manage its behavior. The main configuration areas are:

Environment Variables: Runtime configuration
Server Configurations: Member server definitions
Tool Configurations: Custom tool definitions
Database Configuration: Storage settings
Authentication: Auth strategy settings

MCP Composer Server Configuration

`MCP_BASE_URL`

Description: Base URL for the MCP Composer server endpoint.

Type: URL String

Default: http://0.0.0.0:9000/mcp

Example:

bash

MCP_BASE_URL=http://0.0.0.0:9000/mcp
# For production
MCP_BASE_URL=https://mcp-composer.example.com/mcp

`SERVER_CONFIG_FILE_PATH`

Description: Path to the server configuration JSON file. This file is automatically created when you register a server and contains all registered MCP server configurations.

Type: File Path

Default: mcp_servers.json (in root folder)

Example:

bash

SERVER_CONFIG_FILE_PATH=mcp_servers.json
# Custom path
SERVER_CONFIG_FILE_PATH=/etc/mcp-composer/servers.json

`VERSION_CONFIG_FILE_PATH`

Description: Path to the versioned configuration file that tracks different versions of server configurations.

Type: File Path

Default: versioned_config.json (in root folder)

Example:

bash

VERSION_CONFIG_FILE_PATH=versioned_config.json
# Custom path
VERSION_CONFIG_FILE_PATH=/var/lib/mcp-composer/versions.json

`MCP_USE_LOCAL_FILE_STORAGE`

Description: Enable or disable local file storage for server configurations. When enabled, configurations are stored in local JSON files instead of a database.

Type: Boolean

Default: False

Allowed Values: True, False

Example:

bash

MCP_USE_LOCAL_FILE_STORAGE=True

`VERSION_ADAPTER_TYPE`

Description: Specifies the adapter type for version management. Use file for local file storage or ibm_vault for IBM Secret Manager.

Type: String

Default: file

Allowed Values: file, ibm_vault

Example:

bash

VERSION_ADAPTER_TYPE=file
# For IBM Secret Manager
VERSION_ADAPTER_TYPE=ibm_vault

`MCP_COMPOSER_MODE`

Description: Defines the operational mode for MCP Composer. Affects logging levels, error handling, and debugging features.

Type: String

Default: dev

Allowed Values: dev, prod

Example:

bash

# Development mode (verbose logging, detailed errors)
MCP_COMPOSER_MODE=dev

# Production mode (minimal logging, sanitized errors)
MCP_COMPOSER_MODE=prod

`MCP_MODE`

Description: Transport mode for MCP Composer server communication.

Type: String

Default: stdio

Allowed Values: stdio, sse, http

Example:

bash

# Server-Sent Events mode
MCP_MODE=sse

# Standard I/O mode
MCP_MODE=stdio

# HTTP mode
MCP_MODE=http

Database Configuration

`MCP_DATABASE_TYPE`

Description: Type of database backend to use for storing MCP configurations.

Type: String

Default: local_file

Allowed Values: local_file, postgresql, mongodb, etc.

Example:

bash

# Local file-based storage
MCP_DATABASE_TYPE=local_file

# PostgreSQL database
MCP_DATABASE_TYPE=postgresql

`MCP_DATABASE_FILE_PATH`

Description: Path to the local database file when using local_file database type.

Type: File Path

Default: mcp_servers.json

Example:

bash

MCP_DATABASE_FILE_PATH=mcp_servers.json
# Custom location
MCP_DATABASE_FILE_PATH=/var/lib/mcp-composer/database.json

OAuth Authentication

`ENABLE_OAUTH`

Description: Enable or disable OAuth authentication for MCP Composer.

Type: Boolean

Default: False

Allowed Values: True, False

Example:

bash

# Enable OAuth
ENABLE_OAUTH=True

# Disable OAuth
ENABLE_OAUTH=False

GitHub OAuth

`OAUTH_PROVIDER`

Description: Specifies the OAuth provider.

Type: String

Allowed Values: github, google

Example:

bash

OAUTH_PROVIDER=github

`OAUTH_BASE_URL`

Description: Base URL of your application for OAuth callbacks.

Type: URL String

Example:

bash

OAUTH_BASE_URL=http://localhost:9000
# Production
OAUTH_BASE_URL=https://mcp-composer.example.com

`OAUTH_CLIENT_ID`

Description: OAuth client ID provided by GitHub.

Type: String

Example:

bash

OAUTH_CLIENT_ID=xxxxxxx

`OAUTH_CLIENT_SECRET`

Description: OAuth client secret provided by GitHub.

Type: String (Sensitive)

Example:

bash

OAUTH_CLIENT_SECRET=xxxxxxx

Complete GitHub OAuth Example:

bash

ENABLE_OAUTH=True
OAUTH_PROVIDER=github
OAUTH_BASE_URL=http://localhost:9000
OAUTH_CLIENT_ID=xxxxxxx
OAUTH_CLIENT_SECRET=xxxxxxx

IBM W3 OAuth (New)

`OAUTH_CONFIG_URL`

Description: OpenID Connect configuration URL for IBM W3 authentication.

Type: URL String

Example:

bash

OAUTH_CONFIG_URL=https://preprod.login.w3.ibm.com/oidc/endpoint/default/.well-known/openid-configuration

`OAUTH_INTROSPECTION_URL`

Description: Token introspection endpoint for validating OAuth tokens.

Type: URL String

Example:

bash

OAUTH_INTROSPECTION_URL=https://preprod.login.w3.ibm.com/v1.0/endpoint/default/introspect

Complete IBM W3 OAuth (New) Example:

bash

ENABLE_OAUTH=True
OAUTH_CLIENT_ID=xxxxxxx
OAUTH_CLIENT_SECRET=xxxxxxx
OAUTH_BASE_URL=http://localhost:9000
OAUTH_CONFIG_URL=https://preprod.login.w3.ibm.com/oidc/endpoint/default/.well-known/openid-configuration
OAUTH_INTROSPECTION_URL=https://preprod.login.w3.ibm.com/v1.0/endpoint/default/introspect

IBM W3 OAuth (Old)

`OAUTH_HOST`

Description: Hostname for OAuth server.

Type: String

Example:

bash

OAUTH_HOST=localhost

`OAUTH_PORT`

Description: Port number for OAuth server.

Type: Integer

Example:

bash

OAUTH_PORT=9000

`OAUTH_SERVER_URL`

Description: Full server URL for OAuth.

Type: URL String

Example:

bash

OAUTH_SERVER_URL=http://localhost:9000

`OAUTH_CALLBACK_PATH`

Description: OAuth callback URL path.

Type: URL String

Example:

bash

OAUTH_CALLBACK_PATH=http://localhost:9000/auth/idaas/callback

`OAUTH_AUTH_URL`

Description: Authorization endpoint URL.

Type: URL String

Example:

bash

# IBM W3
OAUTH_AUTH_URL=https://preprod.login.w3.ibm.com/v1.0/endpoint/default/authorize

# GitHub
OAUTH_AUTH_URL=https://github.com/login/oauth/authorize

`OAUTH_TOKEN_URL`

Description: Token endpoint URL for exchanging authorization codes.

Type: URL String

Example:

bash

# IBM W3
OAUTH_TOKEN_URL=https://preprod.login.w3.ibm.com/v1.0/endpoint/default/token

# GitHub
OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token

`OAUTH_MCP_SCOPE`

Description: OAuth scope for MCP Composer.

Type: String

Example:

bash

OAUTH_MCP_SCOPE=user

`OAUTH_PROVIDER_SCOPE`

Description: OAuth scope required by the provider.

Type: String

Example:

bash

OAUTH_PROVIDER_SCOPE=openid

Complete IBM W3 OAuth (Old) Example:

bash

ENABLE_OAUTH=True
OAUTH_HOST=localhost
OAUTH_PORT=9000
OAUTH_SERVER_URL=http://localhost:9000
OAUTH_CALLBACK_PATH=http://localhost:9000/auth/idaas/callback
OAUTH_CLIENT_ID=xxxxxxx
OAUTH_CLIENT_SECRET=xxxxxxx
OAUTH_AUTH_URL=https://preprod.login.w3.ibm.com/v1.0/endpoint/default/authorize
OAUTH_TOKEN_URL=https://preprod.login.w3.ibm.com/v1.0/endpoint/default/token
OAUTH_MCP_SCOPE=user
OAUTH_PROVIDER_SCOPE=openid

OpenTelemetry Configuration

`MCP_TRACING_ENABLED`

Description: Enable or disable distributed tracing with OpenTelemetry.

Type: Boolean

Default: False

Allowed Values: true, false

Example:

bash

MCP_TRACING_ENABLED=true

`MCP_TRACING_PROTOCOL`

Description: Protocol to use for OpenTelemetry tracing.

Type: String

Allowed Values: http, grpc

Example:

bash

MCP_TRACING_PROTOCOL=http
# For gRPC
MCP_TRACING_PROTOCOL=grpc

`OTEL_SERVICE_NAME`

Description: Service name identifier for OpenTelemetry traces.

Type: String

Default: mcp-composer

Example:

bash

OTEL_SERVICE_NAME=mcp-composer
# Custom service name
OTEL_SERVICE_NAME=mcp-composer-production

`OTEL_EXPORTER_OTLP_ENDPOINT`

Description: OpenTelemetry collector endpoint URL.

Type: URL String

Default: http://localhost:4318

Example:

bash

# Local collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Remote collector
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318

`MCP_METRICS_ENABLED`

Description: Enable or disable metrics collection with OpenTelemetry.

Type: Boolean

Default: False

Allowed Values: true, false

Example:

bash

MCP_METRICS_ENABLED=true

`MCP_ENV`

Description: Environment identifier for telemetry data.

Type: String

Allowed Values: dev, staging, prod

Example:

bash

# Development
MCP_ENV=dev

# Staging
MCP_ENV=staging

# Production
MCP_ENV=prod

Complete OpenTelemetry Configuration Example:

bash

MCP_TRACING_ENABLED=true
MCP_TRACING_PROTOCOL=http
OTEL_SERVICE_NAME=mcp-composer
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
MCP_METRICS_ENABLED=true
MCP_ENV=dev

Common Configuration Examples

Development Setup

bash

# Basic dev configuration
MCP_BASE_URL=http://0.0.0.0:9000/mcp
MCP_COMPOSER_MODE=dev
MCP_MODE=sse
MCP_DATABASE_TYPE=local_file
MCP_DATABASE_FILE_PATH=mcp_servers.json
MCP_USE_LOCAL_FILE_STORAGE=True
ENABLE_OAUTH=False

Production Setup with OAuth

bash

# Production configuration
MCP_BASE_URL=https://mcp-composer.example.com/mcp
MCP_COMPOSER_MODE=prod
MCP_MODE=sse
MCP_DATABASE_TYPE=postgresql
ENABLE_OAUTH=True

# IBM W3 OAuth
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_BASE_URL=https://mcp-composer.example.com
OAUTH_CONFIG_URL=https://verify.example.com/oidc/endpoint/default/.well-known/openid-configuration
OAUTH_INTROSPECTION_URL=https://verify.example.com/v1.0/endpoint/default/introspect

# OpenTelemetry
MCP_TRACING_ENABLED=true
MCP_TRACING_PROTOCOL=http
OTEL_SERVICE_NAME=mcp-composer-prod
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
MCP_METRICS_ENABLED=true
MCP_ENV=prod

Server Configurations

Member Servers File

Location: config/member_servers.json

json

[
  {
    "id": "weather-api",
    "type": "http",
    "endpoint": "https://api.openweathermap.org/data/2.5",
    "auth_strategy": "api_key",
    "auth": {
      "api_key": "your-api-key"
    },
    "timeout": 30,
    "retry_attempts": 3,
    "health_check": {
      "enabled": true,
      "endpoint": "/health",
      "interval": 60
    }
  },
  {
    "id": "local-tools",
    "type": "stdio",
    "command": "python",
    "args": ["local_tools.py"],
    "working_directory": "/path/to/tools",
    "env": {
      "PYTHONPATH": "/path/to/tools"
    }
  }
]

Server Types

HTTP/SSE Servers

json

{
  "id": "remote-server",
  "type": "http",
  "endpoint": "https://api.example.com/mcp",
  "auth_strategy": "bearer",
  "auth": {
    "token": "your-token"
  },
  "headers": {
    "User-Agent": "MCP-Composer/1.0"
  },
  "timeout": 30
}

Stdio Servers

json

{
  "id": "local-server",
  "type": "stdio",
  "command": "python",
  "args": ["server.py"],
  "working_directory": "/path/to/server",
  "env": {
    "API_KEY": "your-key"
  }
}

OpenAPI Servers

json

{
  "id": "openapi-server",
  "type": "openapi",
  "open_api": {
    "endpoint": "https://api.example.com",
    "spec_url": "https://api.example.com/openapi.json",
    "custom_routes": "path/to/custom_routes.json"
  },
  "auth_strategy": "basic",
  "auth": {
    "username": "user",
    "password": "pass"
  }
}

GraphQL Servers

json

{
  "id": "graphql-server",
  "type": "graphql",
  "endpoint": "https://graphql.example.com/graphql",
  "auth_strategy": "bearer",
  "auth": {
    "token": "your-token"
  },
  "introspection": true
}

Tool Configurations

Tools File

Location: config/tools.json

json

[
  {
    "name": "weather",
    "tool_type": "curl",
    "curl_config": {
      "value": "curl 'https://api.openweathermap.org/data/2.5/weather?q={{city}}&appid=YOUR_API_KEY'"
    },
    "description": "Get weather information for a city",
    "permission": {
      "user": "read"
    },
    "enabled": true
  },
  {
    "name": "calculate",
    "tool_type": "script",
    "script_config": {
      "value": "def add_numbers(a: float, b: float) -> float:\n    return a + b"
    },
    "description": "Add two numbers",
    "permission": {
      "user": "execute"
    },
    "enabled": true
  }
]

Tool Types

Curl Tools

json

{
  "name": "api_call",
  "tool_type": "curl",
  "curl_config": {
    "value": "curl -X GET 'https://api.example.com/data' -H 'Authorization: Bearer {{token}}'"
  },
  "description": "Make API call",
  "permission": {
    "user": "read"
  }
}

Script Tools

json

{
  "name": "custom_function",
  "tool_type": "script",
  "script_config": {
    "value": "def process_data(data: str) -> dict:\n    # Your custom logic here\n    return {'result': data.upper()}"
  },
  "description": "Process data with custom logic",
  "permission": {
    "user": "execute"
  }
}

OpenAPI Tools

json

{
  "name": "get_user",
  "tool_type": "openapi",
  "openapi_config": {
    "operation": "GET /users/{id}",
    "parameters": {
      "id": "string"
    }
  },
  "description": "Get user by ID",
  "permission": {
    "user": "read"
  }
}

Database Configuration Examples

Local File Database

env

DATABASE_TYPE=local_file
DATABASE_PATH=data/mcp_composer.db

Cloudant Database

env

DATABASE_TYPE=cloudant
CLOUDANT_URL=https://your-account.cloudant.com
CLOUDANT_API_KEY=your-api-key
CLOUDANT_DB_NAME=mcp_composer

Database Configuration File

Location: config/database.json

json

{
  "type": "local_file",
  "path": "data/mcp_composer.db",
  "backup_enabled": true,
  "backup_interval": 3600,
  "backup_path": "data/backups/"
}

Logging Configuration

Log Levels

DEBUG: Detailed debug information
INFO: General information
WARNING: Warning messages
ERROR: Error messages
CRITICAL: Critical errors

Log Format

env

# JSON format (recommended for production)
LOG_FORMAT=json

# Simple format (good for development)
LOG_FORMAT=simple

Log Configuration File

Location: config/logging.json

json

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "json": {
      "class": "pythonjsonlogger.jsonlogger.JsonFormatter",
      "format": "%(timestamp)s %(level)s %(name)s %(message)s"
    }
  },
  "handlers": {
    "console": {
      "class": "logging.StreamHandler",
      "formatter": "json",
      "level": "INFO"
    },
    "file": {
      "class": "logging.FileHandler",
      "filename": "logs/mcp_composer.log",
      "formatter": "json",
      "level": "DEBUG"
    }
  },
  "root": {
    "level": "INFO",
    "handlers": ["console", "file"]
  }
}

Configuration Validation

Validate Configuration

bash

# Validate environment variables
mcp-composer --validate-env

# Validate server configurations
mcp-composer --validate-servers

# Validate tool configurations
mcp-composer --validate-tools

# Validate all configurations
mcp-composer --validate-all

Configuration Schema

MCP Composer uses JSON schemas to validate configurations:

Server Schema: schemas/server_config.json
Tool Schema: schemas/tool_config.json
Environment Schema: schemas/env_config.json

Environment-Specific Configurations

Development

env

LOG_LEVEL=DEBUG
DATABASE_TYPE=local_file
CACHE_ENABLED=false
METRICS_ENABLED=true

Production

env

LOG_LEVEL=INFO
DATABASE_TYPE=cloudant
CACHE_ENABLED=true
METRICS_ENABLED=true
RATE_LIMIT_ENABLED=true

Testing

env

LOG_LEVEL=WARNING
DATABASE_TYPE=fake
CACHE_ENABLED=false
METRICS_ENABLED=false

Configuration Best Practices

Security

Never commit secrets to version control
Use environment variables for sensitive data
Rotate API keys regularly
Use least privilege for permissions
Enable rate limiting in production

Performance

Enable caching for frequently accessed data
Set appropriate timeouts for external services
Use connection pooling for databases
Monitor resource usage with metrics

Reliability

Enable health checks for all servers
Configure retry logic for failed requests
Set up backup for database
Use circuit breakers for external services

Troubleshooting Configuration

Common Issues

Configuration not found

bash

# Check file paths
ls -la config/
ls -la src/.env

Invalid JSON

bash

# Validate JSON files
python -m json.tool config/member_servers.json

Environment variables not loaded

bash

# Check environment file
cat src/.env
# Verify variables are set
env | grep MCP

Debug Configuration

bash

# Enable debug logging
export LOG_LEVEL=DEBUG

# Show configuration on startup
mcp-composer --show-config

# Validate configuration
mcp-composer --validate-config

Next Steps

Quick Start Guide - Get up and running
CLI Usage - Learn command-line options
API Reference - Complete API documentation
Examples - See configuration examples

Configuration ​

Overview ​

MCP Composer Server Configuration ​

MCP_BASE_URL ​

SERVER_CONFIG_FILE_PATH ​

VERSION_CONFIG_FILE_PATH ​

MCP_USE_LOCAL_FILE_STORAGE ​

VERSION_ADAPTER_TYPE ​

MCP_COMPOSER_MODE ​

MCP_MODE ​

Database Configuration ​

MCP_DATABASE_TYPE ​

MCP_DATABASE_FILE_PATH ​

OAuth Authentication ​

ENABLE_OAUTH ​

GitHub OAuth ​

OAUTH_PROVIDER ​

OAUTH_BASE_URL ​

OAUTH_CLIENT_ID ​

OAUTH_CLIENT_SECRET ​

IBM W3 OAuth (New) ​

OAUTH_CONFIG_URL ​

OAUTH_INTROSPECTION_URL ​

IBM W3 OAuth (Old) ​

OAUTH_HOST ​

OAUTH_PORT ​

OAUTH_SERVER_URL ​

OAUTH_CALLBACK_PATH ​

OAUTH_AUTH_URL ​

OAUTH_TOKEN_URL ​

OAUTH_MCP_SCOPE ​

OAUTH_PROVIDER_SCOPE ​

OpenTelemetry Configuration ​

MCP_TRACING_ENABLED ​

MCP_TRACING_PROTOCOL ​

OTEL_SERVICE_NAME ​

OTEL_EXPORTER_OTLP_ENDPOINT ​

MCP_METRICS_ENABLED ​

MCP_ENV ​

Common Configuration Examples ​

Development Setup ​

Production Setup with OAuth ​

Server Configurations ​

Member Servers File ​

Server Types ​

HTTP/SSE Servers ​

Stdio Servers ​

OpenAPI Servers ​

GraphQL Servers ​

Tool Configurations ​

Tools File ​

Tool Types ​

Curl Tools ​

Script Tools ​

OpenAPI Tools ​

Database Configuration Examples ​

Local File Database ​

Cloudant Database ​

Database Configuration File ​

Logging Configuration ​

Log Levels ​

Log Format ​

Log Configuration File ​

Configuration Validation ​

Validate Configuration ​

Configuration Schema ​

Environment-Specific Configurations ​

Development ​

Production ​

Testing ​

Configuration Best Practices ​

Security ​

Performance ​

Reliability ​

Troubleshooting Configuration ​

Common Issues ​

Debug Configuration ​

Next Steps ​

Configuration

Overview

MCP Composer Server Configuration

`MCP_BASE_URL`

`SERVER_CONFIG_FILE_PATH`

`VERSION_CONFIG_FILE_PATH`

`MCP_USE_LOCAL_FILE_STORAGE`

`VERSION_ADAPTER_TYPE`

`MCP_COMPOSER_MODE`

`MCP_MODE`

Database Configuration

`MCP_DATABASE_TYPE`

`MCP_DATABASE_FILE_PATH`

OAuth Authentication

`ENABLE_OAUTH`

GitHub OAuth

`OAUTH_PROVIDER`

`OAUTH_BASE_URL`

`OAUTH_CLIENT_ID`

`OAUTH_CLIENT_SECRET`

IBM W3 OAuth (New)

`OAUTH_CONFIG_URL`

`OAUTH_INTROSPECTION_URL`

IBM W3 OAuth (Old)

`OAUTH_HOST`

`OAUTH_PORT`

`OAUTH_SERVER_URL`

`OAUTH_CALLBACK_PATH`

`OAUTH_AUTH_URL`

`OAUTH_TOKEN_URL`

`OAUTH_MCP_SCOPE`

`OAUTH_PROVIDER_SCOPE`

OpenTelemetry Configuration

`MCP_TRACING_ENABLED`

`MCP_TRACING_PROTOCOL`

`OTEL_SERVICE_NAME`

`OTEL_EXPORTER_OTLP_ENDPOINT`

`MCP_METRICS_ENABLED`

`MCP_ENV`

Common Configuration Examples

Development Setup

Production Setup with OAuth

Server Configurations

Member Servers File

Server Types

HTTP/SSE Servers

Stdio Servers

OpenAPI Servers

GraphQL Servers

Tool Configurations

Tools File

Tool Types

Curl Tools

Script Tools

OpenAPI Tools

Database Configuration Examples

Local File Database

Cloudant Database

Database Configuration File

Logging Configuration

Log Levels

Log Format

Log Configuration File

Configuration Validation

Validate Configuration

Configuration Schema

Environment-Specific Configurations

Development

Production

Testing

Configuration Best Practices

Security

Performance

Reliability

Troubleshooting Configuration

Common Issues

Debug Configuration

Next Steps