This guide shows how to seamlessly integrate ETDI (Enhanced Tool Definition Interface) into your MCP applications.
# Clone and setup
git clone <repository>
cd python-sdk
python3 setup_etdi.py# Initialize ETDI configuration
etdi init-config --provider auth0
# Edit configuration with your OAuth credentials
nano ~/.etdi/config/etdi-config.jsonfrom mcp.etdi import ETDIClient
# Simple client usage
async with ETDIClient.from_config("~/.etdi/config/etdi-config.json") as client:
tools = await client.discover_tools()
for tool in tools:
if tool.verification_status.value == "verified":
await client.approve_tool(tool)# Before (standard MCP)
from mcp.client import ClientSession
session = ClientSession()
tools = await session.list_tools()
# After (ETDI-enhanced)
from mcp.etdi import ETDISecureClientSession, ETDIClient
client = ETDIClient(config)
await client.initialize()
session = ETDISecureClientSession(
verifier=client.verifier,
approval_manager=client.approval_manager
)
tools = await session.list_tools() # Now with security verificationfrom mcp.etdi import ETDIVerifier, ApprovalManager
from mcp.etdi.oauth import OAuthManager
# Add ETDI security to existing MCP client
oauth_manager = OAuthManager()
oauth_manager.register_provider_config("auth0", oauth_config)
verifier = ETDIVerifier(oauth_manager)
approval_manager = ApprovalManager()
# Verify tools before use
for tool in existing_tools:
result = await verifier.verify_tool(tool)
if result.valid:
await approval_manager.approve_tool_with_etdi(tool)# Before (standard MCP server)
from mcp.server.fastmcp import FastMCP
app = FastMCP()
@app.tool()
async def my_tool(param: str) -> str:
return f"Result: {param}"
# After (ETDI-secured)
from mcp.etdi import ETDISecureServer
app = ETDISecureServer(oauth_configs=[oauth_config])
@app.secure_tool(permissions=["read:data", "execute:tools"])
async def my_tool(param: str) -> str:
return f"Secure result: {param}"from mcp.etdi.server import OAuthSecurityMiddleware
# Add security middleware to existing server
middleware = OAuthSecurityMiddleware([oauth_config])
await middleware.initialize()
# Enhance existing tool definitions
enhanced_tool = await middleware.enhance_tool_definition(
existing_tool_definition,
provider_name="auth0"
)-
Create Auth0 Application:
- Go to Auth0 Dashboard
- Create new "Machine to Machine" application
- Authorize for your API
- Note Client ID, Client Secret, Domain
-
Configure ETDI:
{
"oauth_config": {
"provider": "auth0",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"domain": "your-domain.auth0.com",
"audience": "https://your-api.example.com",
"scopes": ["read:tools", "execute:tools"]
}
}-
Create Okta Application:
- Go to Okta Admin Console
- Create new "Service" application
- Configure OAuth settings
- Note Client ID, Client Secret, Domain
-
Configure ETDI:
{
"oauth_config": {
"provider": "okta",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"domain": "your-domain.okta.com",
"scopes": ["etdi.tools.read", "etdi.tools.execute"]
}
}-
Create Azure AD Application:
- Go to Azure Portal
- Register new application
- Create client secret
- Configure API permissions
-
Configure ETDI:
{
"oauth_config": {
"provider": "azure",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"domain": "your-tenant-id",
"scopes": ["https://graph.microsoft.com/.default"]
}
}- Simple cryptographic verification
- No OAuth requirements
- Suitable for development
config = {
"security_level": "basic",
"allow_non_etdi_tools": True,
"show_unverified_tools": True
}- OAuth 2.0 token verification
- Permission-based access control
- Tool change detection
config = {
"security_level": "enhanced",
"oauth_config": oauth_config,
"allow_non_etdi_tools": True,
"show_unverified_tools": False
}- Full OAuth enforcement
- No unverified tools allowed
- Maximum security
config = {
"security_level": "strict",
"oauth_config": oauth_config,
"allow_non_etdi_tools": False,
"show_unverified_tools": False
}# Discover tools with OAuth verification
etdi discover --provider auth0 --client-id <id> --client-secret <secret> --domain <domain>
# Use configuration file
etdi discover --config ~/.etdi/config/etdi-config.json# Debug OAuth token
etdi debug-token <jwt-token>
# Save report to file
etdi debug-token <jwt-token> --format json --output token-report.json# Test OAuth provider connectivity
etdi validate-provider --config ~/.etdi/config/etdi-config.json
# Test specific provider
etdi validate-provider --provider auth0 --client-id <id> --domain <domain># Analyze tool security
etdi analyze-tool tool-definition.json
# Generate JSON report
etdi analyze-tool tool-definition.json --format json --output security-report.json# Build and run with Docker Compose
cd deployment/docker
docker-compose up -d
# Check status
docker-compose ps
docker-compose logs etdi-server# Set OAuth credentials
export ETDI_CLIENT_ID="your-client-id"
export ETDI_CLIENT_SECRET="your-client-secret"
export ETDI_DOMAIN="your-domain.auth0.com"
export ETDI_AUDIENCE="https://your-api.example.com"
# Run ETDI server
python -m mcp.etdi.serverapiVersion: apps/v1
kind: Deployment
metadata:
name: etdi-server
spec:
replicas: 3
selector:
matchLabels:
app: etdi-server
template:
metadata:
labels:
app: etdi-server
spec:
containers:
- name: etdi-server
image: etdi-server:latest
ports:
- containerPort: 8000
env:
- name: ETDI_CLIENT_ID
valueFrom:
secretKeyRef:
name: etdi-oauth
key: client-id
- name: ETDI_CLIENT_SECRET
valueFrom:
secretKeyRef:
name: etdi-oauth
key: client-secretfrom mcp.etdi.inspector import SecurityAnalyzer, TokenDebugger, OAuthValidator
# Analyze tool security
analyzer = SecurityAnalyzer()
result = await analyzer.analyze_tool(tool)
print(f"Security Score: {result.overall_security_score}/100")
# Debug OAuth tokens
debugger = TokenDebugger()
debug_info = debugger.debug_token(token)
print(debugger.format_debug_report(debug_info))
# Validate OAuth providers
validator = OAuthValidator()
validation_result = await validator.validate_provider("auth0", oauth_config)# Check ETDI client health
async with ETDIClient(config) as client:
stats = await client.get_stats()
print(f"Healthy providers: {stats['oauth_providers']}")
print(f"Verification cache: {stats['verification']['cache_size']}")import logging
# Enable ETDI logging
logging.getLogger('mcp.etdi').setLevel(logging.INFO)
# Custom log handler
handler = logging.FileHandler('/var/log/etdi.log')
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logging.getLogger('mcp.etdi').addHandler(handler)- Use Enhanced or Strict security levels in production
- Rotate OAuth credentials regularly
- Monitor token expiration and refresh proactively
- Audit tool approvals and permissions regularly
- Use HTTPS for all OAuth communications
- Enable verification caching for better performance
- Use batch operations for multiple tools
- Monitor cache hit rates and adjust TTL as needed
- Implement connection pooling for OAuth providers
- Track security events and approval changes
- Monitor OAuth provider health and response times
- Set up alerts for security violations
- Log all tool invocations for audit trails
- Use Basic security level for development
- Test with multiple OAuth providers for compatibility
- Validate tool definitions before deployment
- Use inspector tools for debugging
# Debug the token
etdi debug-token <token>
# Check provider connectivity
etdi validate-provider --config <config>
# Verify configuration
python -c "from mcp.etdi import OAuthConfig; print(OAuthConfig.from_file('<config>').validate())"# Check security level
etdi discover --config <config> --security-level basic
# Verify MCP server connectivity
curl -X POST <mcp-server>/tools
# Check logs
tail -f ~/.etdi/logs/etdi.log# Check tool approvals
python -c "from mcp.etdi import ApprovalManager; am = ApprovalManager(); print(am.list_approvals())"
# Re-approve tool
etdi approve-tool <tool-id>
# Check permission scopes
etdi analyze-tool <tool-definition>- Check logs:
~/.etdi/logs/etdi.log - Run diagnostics:
etdi --help - Validate configuration:
etdi validate-provider - Test components:
python -m mcp.etdi.test - Review examples:
examples/etdi/
- Install ETDI: Run
python3 setup_etdi.py - Configure OAuth: Set up OAuth provider
- Update client code: Replace
ClientSessionwithETDISecureClientSession - Update server code: Replace
FastMCPwithETDISecureServer - Test integration: Run examples and verify functionality
- Deploy gradually: Start with Basic security, move to Enhanced/Strict
ETDI maintains backward compatibility with standard MCP:
- Standard MCP tools work with ETDI clients (with warnings)
- ETDI tools work with standard MCP clients (without security)
- Gradual migration is supported through security levels
This integration guide provides everything needed to seamlessly adopt ETDI in your MCP applications.