Sign inSign up

suayb/kitezh-mcp

By suayb

•Updated 28 days ago

Kitezh MCP Server image

Image
0

2.8K

suayb/kitezh-mcp repository overview

⁠Kitezh MCP Server

Kitezh MCP Server is a separately deployed Model Context Protocol (MCP) service with read-only tools enabled by default and guarded, opt-in write tools for the Kitezh identity platform. It uses Spring Boot, Spring AI, and Streamable HTTP, and runs as a GraalVM Native Image executable compressed with UPX. The published image supports linux/amd64 and linux/arm64.

The MCP endpoint listens on port 10000 at /mcp. The server has no database dependency: it authenticates the MCP user's OAuth access token and forwards that same token to the Kitezh Administration API.

⁠Image

docker pull suayb/kitezh-mcp:latest

Official links:

Docker selects the matching architecture from the latest multi-architecture manifest. Validated v* releases publish versioned architecture images such as 0.1.0-amd64 and 0.1.0-arm64, then combine them into the versioned 0.1.0 and latest manifests. The MCP Render deployment is pinned to the verified image digest.

⁠Capabilities

  • Stateless Streamable HTTP MCP endpoint at /mcp
  • OAuth 2.0 bearer-token authentication with issuer, audience, and mcp.read/mcp.write scope validation
  • Protected Resource Metadata at /.well-known/oauth-protected-resource
  • Forwarding the validated user bearer token to the Kitezh Administration API
  • Read tools for Kitezh context, users, groups, OAuth clients, sessions, and audit events
  • Eight opt-in preview/apply write tools for user status, group membership, and single-session revocation
  • Health, readiness, liveness, metrics, and Prometheus endpoints
  • Optional OTLP metrics, traces, and logs for Grafana Cloud or an OpenTelemetry Collector
  • GraalVM Native Image runtime assembled with the Jib Native Image extension

Write toolsets are excluded from all and require mcp.write, an eligible user role, and explicit server-side enablement. Each write uses a caller-bound, five-minute, single-use preview and checks for stale target state before applying. The client must request user confirmation before an apply_* call. The server never connects directly to the Kitezh database and never returns passwords, tokens, client secrets, or recovery codes.

⁠Run the image

The MCP resource URL must match the resource audience configured in the Kitezh Authorization Server. The Administration API must accept the forwarded token and enforce the MCP purpose-token route/method allowlist and the existing role authorization rules.

docker run --rm -p 10000:10000 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e SERVER_PORT=10000 \
  -e APP_AUTHORIZATIONSERVER_ISSUER=https://kitezh.onrender.com \
  -e APP_SECURITY_AUDIENCE=https://kitezh-mcp.onrender.com/mcp \
  -e APP_API_BASE_URL=https://kitezh.onrender.com \
  -e APP_MCP_PUBLIC_URL=https://kitezh-mcp.onrender.com/mcp \
  -e MANAGEMENT_OPENTELEMETRY_ENABLED=true \
  -e MANAGEMENT_TRACING_EXPORT_ENABLED=true \
  -e MANAGEMENT_TRACING_EXPORT_OTLP_ENABLED=true \
  -e MANAGEMENT_LOGGING_EXPORT_OTLP_ENABLED=true \
  -e MANAGEMENT_OTLP_METRICS_EXPORT_ENABLED=true \
  -e MANAGEMENT_OPENTELEMETRY_TRACING_EXPORT_OTLP_ENDPOINT='<OTLP_COLLECTOR_URL>/v1/traces' \
  -e MANAGEMENT_OPENTELEMETRY_LOGGING_EXPORT_OTLP_ENDPOINT='<OTLP_COLLECTOR_URL>/v1/logs' \
  -e MANAGEMENT_OTLP_METRICS_EXPORT_URL='<OTLP_COLLECTOR_URL>/v1/metrics' \
  suayb/kitezh-mcp:latest

The native image includes OTLP exporter support so deployments can provide collector URLs at runtime. Supply valid trace, log, and metrics endpoints when running the published image. Store collector authorization headers in the deployment secret manager.

Check the server's readiness:

curl http://localhost:10000/actuator/health/readiness

⁠Connect an MCP client

Kitezh currently uses pre-registered OAuth clients and does not provide Dynamic Client Registration. Register a separate public OAuth client for each MCP host in Kitezh. Allowlist that host's exact localhost callback URI, enable Authorization Code with PKCE S256, and grant openid and mcp.read; add mcp.write only for hosts allowed to call explicitly enabled write tools.

⁠Claude Code

Register http://localhost:8765/callback as the callback URI on the Claude Code client, then run:

claude mcp add --transport http \
  --client-id '<claude-oauth-client-id>' \
  --callback-port 8765 \
  kitezh https://kitezh-mcp.onrender.com/mcp

Run /mcp in Claude Code and complete the Kitezh sign-in in the browser. The registered callback must match the callback port exactly.

⁠Codex

Register the exact localhost callback URI requested by Codex for its OAuth client, then add the server:

codex mcp add kitezh \
  --url https://kitezh-mcp.onrender.com/mcp \
  --oauth-client-id '<codex-oauth-client-id>'

Run codex mcp login kitezh and finish signing in through the browser. The Codex CLI and IDE extension use the same MCP configuration.

For MCP Inspector, configure the seeded mcp-client OAuth client with callback http://localhost:6274/oauth/callback and scope mcp.read; request mcp.write only when testing a write toolset.

⁠Configuration

VariableDefaultPurpose
SERVER_PORT10000HTTP listen port
SPRING_PROFILES_ACTIVESpring's default profileSelect the Spring profile; set to prod for deployment
APP_AUTHORIZATIONSERVER_ISSUERhttps://kitezh.onrender.comOAuth issuer used to validate user tokens; follows the backend configuration property
APP_SECURITY_JWK_SET_URI<issuer>/oauth2/jwksOverride the Authorization Server signing-key endpoint
APP_SECURITY_AUDIENCEhttps://kitezh-mcp.onrender.com/mcpRequired audience on MCP access tokens
APP_API_BASE_URLhttp://localhost:9090Kitezh Administration API base URL
APP_MCP_PUBLIC_URLhttps://kitezh-mcp.onrender.com/mcpPublic MCP resource identifier
APP_CORS_ALLOWED_ORIGINSapp://renderer,http://localhost:6274,http://127.0.0.1:6274Browser origins allowed by MCP CORS; explicitly listed localhost origins also permit matching localhost Host values
APP_MCP_TOOLSETSallEnabled toolsets. all excludes users_write, groups_write, and sessions_write; combine all with a named write toolset, such as all,users_write, to opt in
APP_MCP_ADDITIONAL_TOOLSemptyExact comma-separated MCP tool names to add to the selected toolsets
APP_MCP_TOOL_ALLOWLIST*Exact comma-separated MCP tool names allowed by this deployment, intersected with selected toolsets, additional tools, and caller roles; * allows all selected names; scope and caller roles still apply
APP_LOG_CLIENT_ENABLEDfalseEnable redacted outbound HTTP request/response logs
APP_LOG_CLIENT_LEVELBASICOutbound detail level: BASIC, HEADERS, or FULL
APP_LOG_CLIENT_EXCLUDE_PATHSemptyComma-separated path prefixes excluded from outbound logs
APP_LOG_SERVER_ENABLEDtrueEnable inbound MCP access logs
APP_LOG_SERVER_LEVELBASICInbound detail level: BASIC, HEADERS, or FULL
APP_LOG_SERVER_EXCLUDE_PATHShealth and metrics endpointsComma-separated regular expressions excluded from inbound access logs
APP_LOG_SERVER_FILE_ENABLEDfalseWrite access logs to a separate rolling file
APP_LOG_SERVER_FILE_PATHlogs/application-access.logInbound access log file path
APP_LOG_FILE_ENABLEDfalseWrite application logs to a rolling file
APP_LOG_FILE_PATHlogs/application.logApplication log file path
APP_LOG_SYSLOG_ENABLEDfalseEnable Syslog output
APP_LOG_SYSLOG_HOSTlocalhostSyslog host
APP_LOG_SYSLOG_PORT514Syslog port
APP_LOG_SYSLOG_FACILITYUSERSyslog facility
APP_LOG_SYSLOG_OUTPUTdefaultSyslog output format; json enables structured output
APP_LOG_SYSLOG_JSON_FORMATdefaultStructured Syslog format, such as ecs or logstash
APP_LOG_ASYNC_ENABLEDtrueSend configured appenders through asynchronous queues
APP_LOG_ASYNC_QUEUE_SIZE512Async appender queue size
APP_LOG_ASYNC_NEVER_BLOCKfalseDrop log events instead of blocking when an async queue is full
APP_LOG_MAX_BODY_BYTES8192Maximum text body size considered for logging; larger/unknown bodies are omitted
APP_LOG_OBFUSCATE_REPLACEMENT***Replacement for sensitive values in logs
APP_LOG_OBFUSCATE_HEADERSAuthorization and cookie headersComma-separated sensitive header names
APP_LOG_OBFUSCATE_BODY_FIELDSCommon token and credential fieldsComma-separated sensitive JSON/form body field names
APP_LOG_OBFUSCATE_PARAMETERSCommon token and OAuth parametersComma-separated sensitive query/form parameter names
LOGGING_STRUCTURED_FORMAT_CONSOLEdefaultConsole format; set to json or ecs for structured logs
LOGGING_STRUCTURED_FORMAT_FILEdefaultFile format; set to json or ecs for structured logs
LOGGING_STRUCTURED_ECS_SERVICE_NAMEkitezh-mcpECS service name
LOGGING_STRUCTURED_ECS_SERVICE_ENVIRONMENTActive Spring profileECS deployment environment
MANAGEMENT_OPENTELEMETRY_ENABLEDfalseEnable OpenTelemetry resource/export configuration
MANAGEMENT_TRACING_EXPORT_ENABLEDfalseEnable trace export
MANAGEMENT_TRACING_EXPORT_OTLP_ENABLEDfalseEnable OTLP trace export
MANAGEMENT_TRACING_SAMPLING_PROBABILITY1.0Fraction of traces to sample
MANAGEMENT_TRACING_EXEMPLARS_INCLUDEsampled-tracesTrace exemplars attached to metrics
MANAGEMENT_LOGGING_EXPORT_OTLP_ENABLEDfalseEnable OTLP log export
MANAGEMENT_OTLP_METRICS_EXPORT_ENABLEDfalseEnable OTLP metric export
MANAGEMENT_OPENTELEMETRY_TRACING_EXPORT_OTLP_ENDPOINTemptyOTLP trace endpoint
MANAGEMENT_OPENTELEMETRY_LOGGING_EXPORT_OTLP_ENDPOINTemptyOTLP log endpoint
MANAGEMENT_OTLP_METRICS_EXPORT_URLemptyOTLP metrics endpoint

Keep OTLP authorization headers and deployment credentials in the platform's secret manager. Never put them in source control, the image, or a shared desktop MCP configuration.

Inbound and outbound body, header, and parameter redaction follows the shared APP_LOG_OBFUSCATE_* settings. Cookie values are protected through the Cookie and Set-Cookie header rules. Outbound logging is opt-in; FULL mode can include non-sensitive response content and should only be used for short diagnostic windows. Inbound access logging defaults to BASIC; HEADERS and FULL add more request details and should be enabled only for short diagnostic windows.

Toolset, additional-tools, and allowlist values are operator-controlled deployment settings. The effective catalog is the union of selected toolsets and additional tools, intersected with APP_MCP_TOOL_ALLOWLIST and the caller's role permissions. Client headers and tool arguments cannot widen these server-side limits. An empty allowlist disables all tools.

⁠Deploy

The repository Render Blueprint runs Kitezh MCP as a separate Web Service in Frankfurt, with an independent URL, configuration, secrets, readiness check, and release lifecycle. Tagged MCP releases build native binaries on GraalVM, compress them with UPX, publish architecture images through Jib, create multi-architecture Docker Hub tags, and deploy the verified image digest to Render.

The MCP service calls Kitezh over its API. Configure the API base URL to use Render private networking when available. The MCP and Kitezh services must be deployed with compatible API contracts.

⁠Health and management endpoints

GET /actuator/health
GET /actuator/health/liveness
GET /actuator/health/readiness
GET /actuator/metrics
GET /actuator/prometheus

Keep management endpoints private to the deployment platform or cluster.

Tag summary

Content type

Image

Digest

sha256:879b8f005…

Size

25.6 MB

Last updated

28 days ago

docker pull suayb/kitezh-mcp