Skip to main content
Version: 0.0.2

Integrated Server Architecture

The Integrated Server combines both MCP and webhook server functionality into a single FastAPI application. This document details the architecture, implementation, and deployment patterns for the unified server approach.

Overview​

The integrated server provides a comprehensive solution that handles both MCP client requests and Slack webhook events in a single deployment. This approach simplifies deployment, reduces operational overhead, and enables unified configuration and monitoring.

Architecture Components​

Common Instance Management

The Integrated Server uses the common instance management design shared across all server types in this project. For detailed information about factory patterns, singleton management, token handling, and testing support, see the Common Instance Management documentation.

Integrated Application Factory​

The core integration function that creates a unified FastAPI app:

from slack_mcp.integrate.server import create_integrated_app


def create_integrated_app(
        token: Optional[str] = None,
        mcp_transport: str = "sse",
        mcp_mount_path: Optional[str] = "/mcp",
        retry: int = 3,
) -> FastAPI:
    # Create webhook server as base
    app = create_slack_app()

    # Initialize shared Slack client
    initialize_slack_client(token, retry=retry)

    # Mount MCP server based on transport type
    if mcp_transport == "sse":
        mcp_app = _server_instance.sse_app(mount_path=mcp_mount_path)
        app.mount(mcp_mount_path or "/mcp", mcp_app)
    elif mcp_transport == "streamable-http":
        mcp_app = _server_instance.streamable_http_app()
        # Merge routes for HTTP streaming
        for route in mcp_app.routes:
            app.routes.append(route)

    return app

Unified FastAPI Application​

The integrated server uses FastAPI as the foundation, providing:

  • Webhook Endpoints: /slack/events for Slack event processing
  • MCP Endpoints: Mounted at configurable path (default: /mcp)
  • Health Checks: Unified health monitoring for both components
  • OpenAPI Documentation: Combined API documentation

Shared Resource Management​

Slack Client Sharing​

Both MCP tools and webhook processing use the same Slack client instance:

# Shared client initialization
from slack_mcp.client.manager import initialize_slack_client

initialize_slack_client(token=slack_token, retry=3)

Benefits:

  • Connection pooling efficiency
  • Consistent token management
  • Unified rate limiting
  • Shared authentication state

Configuration Management​

Centralized configuration for both components:

# Environment variables affecting both components
SLACK_BOT_TOKEN=xoxb-...           # Shared Slack authentication
SLACK_SIGNING_SECRET=...           # Webhook verification
MCP_TRANSPORT=sse                  # MCP transport selection
MCP_MOUNT_PATH=/mcp               # MCP endpoint path
SLACK_EVENTS_TOPIC=slack.events   # Webhook event publishing

Transport Configuration​

Server-Sent Events (SSE) Mode​

Default transport for browser-compatible MCP integration:

# SSE transport mounted at /mcp
mcp_app = server.sse_app(mount_path="/mcp")
app.mount("/mcp", mcp_app)

Endpoint Structure:

  • Webhook: POST /slack/events
  • MCP SSE: GET /mcp/sse
  • Health: GET /health

HTTP Streaming Mode​

RESTful HTTP transport integration:

# HTTP streaming routes merged into main app
mcp_app = server.streamable_http_app()
for route in mcp_app.routes:
    app.routes.append(route)

Endpoint Structure:

  • Webhook: POST /slack/events
  • MCP Tools: POST /call_tool, GET /list_tools, etc.
  • Health: GET /health

Deployment Patterns​

Single Container Deployment​

Unified deployment with Docker:

FROM python:3.11-slim
COPY . /app
WORKDIR /app
RUN pip install -e .
EXPOSE 3000
CMD ["slack-integrated-server", "--transport", "sse", "--port", "3000"]

Environment Configuration:

environment:
  - SLACK_BOT_TOKEN=xoxb-your-token
  - SLACK_SIGNING_SECRET=your-signing-secret
  - MCP_TRANSPORT=sse
  - MCP_MOUNT_PATH=/mcp
  - PORT=3000

Kubernetes Deployment​

Scalable container orchestration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: slack-mcp-integrated
spec:
  replicas: 3
  selector:
    matchLabels:
      app: slack-mcp-integrated
  template:
    metadata:
      labels:
        app: slack-mcp-integrated
    spec:
      containers:
      - name: server
        image: slack-mcp-server:latest
        ports:
        - containerPort: 3000
        env:
        - name: SLACK_BOT_TOKEN
          valueFrom:
            secretKeyRef:
              name: slack-secrets
              key: bot-token
        - name: SLACK_SIGNING_SECRET
          valueFrom:
            secretKeyRef:
              name: slack-secrets
              key: signing-secret
---
apiVersion: v1
kind: Service
metadata:
  name: slack-mcp-service
spec:
  selector:
    app: slack-mcp-integrated
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: LoadBalancer

Cloud Platform Deployment​

Heroku​

# Deploy to Heroku
heroku create your-slack-mcp-app
heroku config:set SLACK_BOT_TOKEN=xoxb-your-token
heroku config:set SLACK_SIGNING_SECRET=your-secret
heroku config:set MCP_TRANSPORT=sse
git push heroku main

Google Cloud Run​

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: slack-mcp-integrated
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/maxScale: "10"
    spec:
      containers:
      - image: gcr.io/project-id/slack-mcp-server
        ports:
        - containerPort: 3000
        env:
        - name: SLACK_BOT_TOKEN
          value: "xoxb-your-token"
        - name: MCP_TRANSPORT
          value: "sse"

Configuration Options​

CLI Configuration​

slack-integrated-server \
  --transport sse \
  --mount-path /mcp \
  --host 0.0.0.0 \
  --port 3000 \
  --log-level INFO \
  --retry 3

Environment Variables​

Required​

  • SLACK_BOT_TOKEN: Slack bot token for MCP tools
  • SLACK_SIGNING_SECRET: Signing secret for webhook verification

Optional​

  • MCP_TRANSPORT: Transport mechanism (sse, streamable-http)
  • MCP_MOUNT_PATH: Mount path for MCP endpoints
  • SLACK_EVENTS_TOPIC: Queue topic for webhook events
  • QUEUE_BACKEND_TYPE: Queue backend selection
  • HOST: Server bind address
  • PORT: Server port
  • LOG_LEVEL: Logging verbosity

Transport-Specific Configuration​

SSE Transport​

# Mount path affects SSE endpoint
MCP_MOUNT_PATH=/api/mcp  # SSE available at /api/mcp/sse

HTTP Streaming​

# Routes merged directly into app
# No mount path required, routes at root level

Client Integration​

MCP Client Connection​

SSE Transport​

// Browser-based MCP client
const client = new MCPClient({
  transport: 'sse',
  url: 'https://your-server.com/mcp/sse'
});

HTTP Streaming​

# Python MCP client
from mcp import Client
from mcp.client.http import HttpTransport

transport = HttpTransport("https://your-server.com")
client = Client(transport)

Webhook Configuration​

Configure Slack app webhook URL:

https://your-server.com/slack/events

Monitoring and Observability​

Health Checks​

Unified health endpoints for both components:

@app.get("/health")
async def health_check():
    return {
        "status": "healthy",
        "components": {
            "mcp_server": "ready",
            "webhook_server": "ready",
            "slack_client": "connected",
            "queue_backend": "connected"
        },
        "timestamp": datetime.utcnow().isoformat()
    }

Metrics Collection​

  • Request Metrics: HTTP request/response statistics
  • MCP Metrics: Tool usage and performance
  • Webhook Metrics: Event processing throughput
  • Error Metrics: Error rates and types

Logging Strategy​

Structured logging with correlation IDs:

import structlog

logger = structlog.get_logger()

# Webhook request logging
logger.info("webhook_event_received", 
           event_type=event_type, 
           team_id=team_id,
           correlation_id=correlation_id)

# MCP tool logging
logger.info("mcp_tool_executed",
           tool_name=tool_name,
           execution_time=execution_time,
           correlation_id=correlation_id)

Error Handling​

Unified Error Responses​

Consistent error format across both components:

{
  "error": {
    "code": "COMPONENT_ERROR",
    "message": "Human-readable error message",
    "component": "mcp|webhook",
    "details": {
      "specific_error_data": "..."
    },
    "correlation_id": "uuid-correlation-id"
  }
}

Circuit Breaker Pattern​

Resilience for external dependencies:

from circuitbreaker import circuit

@circuit(failure_threshold=5, recovery_timeout=30)
async def slack_api_call():
    # Slack API interaction with circuit breaker
    pass

Performance Considerations​

Resource Sharing Benefits​

  • Memory Efficiency: Single application instance
  • Connection Pooling: Shared HTTP connections
  • Process Management: Reduced overhead
  • Monitoring Simplicity: Single deployment to monitor

Scaling Strategies​

  • Horizontal Scaling: Multiple container instances
  • Load Balancing: Distribute requests across instances
  • Auto-scaling: Based on CPU/memory/request metrics
  • Regional Deployment: Multiple regions for latency

Security​

Unified Security Model​

  • Token Management: Single source of truth for Slack credentials
  • Request Verification: Webhook signature validation
  • HTTPS Enforcement: TLS termination at load balancer
  • Secret Management: Environment-based configuration

Network Security​

  • Firewall Rules: Restrict inbound traffic to HTTPS
  • API Gateway: Optional API gateway for additional security
  • Rate Limiting: Application-level rate limiting
  • DDoS Protection: Cloud provider DDoS mitigation

This integrated server architecture provides a comprehensive, production-ready solution for deploying both MCP and webhook functionality in a unified, maintainable, and scalable manner.