Mittwald MCP Server

The Mittwald MCP server exposes 116 tools that let MCP clients (Claude, ChatGPT, MCP Inspector, Cursor, Codex CLI) manage Mittwald hosting infrastructure on behalf of a user. Authentication flows through an OAuth bridge that fronts Mittwald's OAuth 2.1 endpoints using Authorization Code + PKCE only. Mittwald treats the bridge as a public client: there is no Mittwald-issued client secret to manage. The bridge mints its own secrets for downstream confidential MCP clients (e.g. Claude Desktop) and verifies them before issuing JWTs.

Mittwald remains authoritative for scopes and consent — the bridge renders no consent page of its own, and the scope string inside each issued JWT comes straight from Mittwald's token response. Clients register their redirect URI through /register (Dynamic Client Registration); see ARCHITECTURE.md for why that is mandatory.

Production Deployment

Both run as containers in one mittwald container stack alongside a managed Redis, described by the Terraform config in deploy/. Pushing a v* tag builds both images and applies that config — see DEPLOY.md.

Connect a client with:

claude mcp add --transport http mittwald https://mcp.mittwald.de/mcp

Related MCP server: mcp-shell

Repository Layout

src/                        # MCP server (JWT validation, sessions, tool handlers + definitions)
packages/
  oauth-bridge/             # OAuth 2.1 proxy to Mittwald OAuth (Koa)
  mittwald-cli-core/        # Mittwald CLI business logic as an importable library
deploy/                     # Terraform config for the production container stack
docs/                       # Operator runbooks and the two documentation sites
tests/                      # Unit, integration, e2e, security, smoke, functional suites
evals/                      # Agent-native E2E harness and prompt corpus

Development Setup

Prerequisite: Node.js 24.11.0 or higher (see .nvmrc / .node-version). Earlier LTS releases (e.g. Node 18, Node 20) cannot run @mittwald/cli@1.12.0 because its dependencies require the new /v regular-expression flag.

Building Locally

This is a monorepo with workspace packages that must be built in order.

1. Install all dependencies:

   npm ci

2. Build the project (including all workspace dependencies):

   npm run build:all

   Or build workspace packages individually:

   cd packages/mittwald-cli-core && npm run build && cd ../..
   cd packages/oauth-bridge && npm run build && cd ../..
   npm run build

OR use Docker (recommended for production builds):

docker build --no-cache -t mittwald/mcp .

Local SSL Certificates

For local HTTPS development, generate certificates using mkcert:

# Install mkcert (macOS)
brew install mkcert
mkcert -install

# Generate certificates
mkdir -p ssl
mkcert -key-file ssl/localhost+2-key.pem -cert-file ssl/localhost+2.pem localhost 127.0.0.1 ::1

The server uses these paths by default, or set SSL_KEY_PATH and SSL_CERT_PATH to override.

Running for Development

1. Configure scopes and Mittwald OAuth details:

   export MITTWALD_ISSUER=https://id.mittwald.de
   export MITTWALD_CLIENT_ID=mittwald-mcp-server
   export MITTWALD_REDIRECT_URI=https://your-local-proxy/mittwald/callback

   The OAuth and MCP services both read their scope catalogue from config/mittwald-scopes.json. Update that file (or point MITTWALD_SCOPE_CONFIG_PATH at an override) to change supported or default scopes—no code changes required.

2. Run the OAuth bridge:

   npm run --workspace=packages/oauth-bridge dev

3. Run the MCP server:

   npm run build && node build/index.js

   Use npm run watch in a second shell to recompile on change.

Each service exposes health and debugging endpoints; consult ARCHITECTURE.md for flow diagrams and environment specifics.

Prometheus Metrics

Both the MCP Server and OAuth Bridge expose Prometheus-compatible metrics at /metrics.

Configuration

Set METRICS_ENABLED=false to completely disable metrics collection and the /metrics endpoint.

When both METRICS_USER and METRICS_PASS are set, Basic Authentication is required to access the metrics endpoint.

Available Metrics

MCP Server

OAuth Bridge

Both services also expose default Node.js metrics (nodejs_*, process_*).

Prometheus Scrape Configuration

In production both containers require Basic auth (METRICS_USER / METRICS_PASS are set by Terraform). Ports are 8080 for the MCP server and 3000 for the bridge:

scrape_configs:
  - job_name: 'mittwald-mcp-server'
    static_configs:
      - targets: ['mcp-server:8080']
    basic_auth:
      username: metrics
      password: your-secret

  - job_name: 'mittwald-oauth-bridge'
    static_configs:
      - targets: ['oauth-bridge:3000']
    basic_auth:
      username: metrics
      password: your-secret

Example PromQL Queries

# Tool call rate per minute
rate(mcp_tool_calls_total[1m])

# Tool error rate
sum(rate(mcp_tool_calls_total{status="error"}[5m])) / sum(rate(mcp_tool_calls_total[5m]))

# 95th percentile tool latency
histogram_quantile(0.95, rate(mcp_tool_duration_seconds_bucket[5m]))

# OAuth token success rate
sum(rate(oauth_token_requests_total{status="success"}[5m])) / sum(rate(oauth_token_requests_total[5m]))

Operational Notes

• Revoke access in mStudio to force downstream clients to re-authorize.

• The OAuth bridge logs the loaded scope configuration (counts, defaults, config file path). Any mismatch between Mittwald discovery and the configured list is surfaced there.

• Ensure Redis is available to both the bridge and MCP server (BRIDGE_STATE_STORE=redis, shared session store).

Testing

• Run npm run lint, npm run type-check, and npm run test:unit for fast local feedback.

• npm run test:integration exercises Redis-backed session flows and bridge JWT verification.

• npm run test:e2e:mcp drives a full OAuth + MCP tool cycle against the mock stack.

• See tests/README.md for the complete matrix and environment requirements.

Security

This repository uses GitHub's native security features:

• Dependabot: Automatically creates PRs for vulnerable dependencies (configured in .github/dependabot.yml)

• CodeQL: Static analysis for security vulnerabilities on PRs and weekly scans (.github/workflows/codeql.yml)

• Secret Scanning: Prevents accidental commit of secrets (enable in repository Settings → Security)

• npm audit: .github/workflows/security-check.yml fails PRs with high/critical advisories

Responding to Security Alerts

1. Dependabot alerts: Review and merge dependency update PRs promptly. Security updates are grouped and labeled for easy identification.

2. CodeQL findings: Address issues before merging PRs. The workflow blocks PRs with HIGH/CRITICAL severity findings.

3. Secret scanning alerts: Rotate any compromised secrets immediately and revoke associated access.

Coverage Reports

• mw-cli-coverage.json contains machine-readable coverage stats for the Mittwald CLI.

• Validate the artifact with config/mw-cli-coverage.schema.json (e.g. npx ajv validate -s config/mw-cli-coverage.schema.json -d mw-cli-coverage.json).

• Regenerate with npm run coverage:generate and commit both the JSON and docs/mittwald-cli-coverage.md. Only rerun when tool metadata, exclusion lists, or the Mittwald CLI version change—routine commits that don’t touch those inputs can skip regeneration.

• Intentional gaps live in config/mw-cli-exclusions.json. Update this allowlist (with rationale) whenever a missing CLI command is acceptable—CI fails if stats.missingCount is greater than zero.

• Quick commands:

  • npm run coverage:generate – rebuild artifacts when coverage inputs change.

  • npm run check:cli-version – warn when Dockerfile pins drift from npm.

• See docs/coverage.md for the full runbook covering CI guards and allowlist policy.

Documentation

End-user docs are split across two static sites:

• Setup & Guides in docs/setup-and-guides/ (human-perspective onboarding, how-to, tutorials, runbooks, explainers)

• Tool Reference in docs/reference/ (tool-by-tool reference pages and API-level details)

The Tool Reference is generated from the tool registry; see docs/reference/README.md before editing it.

Operator runbooks:

• docs/OPERATIONS-START-HERE.md (operator entrypoint)

• docs/DOCS-SITES-OPERATIONS.md (build and verify both documentation sites)

• docs/FUNCTIONAL-TESTING-OPERATIONS.md (run functional MCP testing in real agents against deployed endpoints)

One-command build for both sites:

cd docs
./build-all.sh local

For deployment-specific details, see DEPLOY.md.

For questions or onboarding guidance, start with ARCHITECTURE.md and docs/INDEX.md (docs navigation). LLM/agent operators should read docs/LLM-AGENTS.md.

For developer documentation on integrating with Mittwald MCP, see the setup guides in docs/setup-and-guides/ or visit the deployed documentation site.