Multi-Service MCP Profile and Configuration Model

Status: Design (no implementation in this repo yet)
Issue: #76 (parent umbrella: #75; boundary decision: ADR-0001, #71)
Date: 2026-07-02

1. Purpose and Scope

Extend the existing Gitea execution-profile model (docs/gitea-execution-profiles.md) into a generic per-service MCP profile/config model. This supports integrating Jenkins and GlitchTip into the MCP Control Plane while strictly preserving isolation and fail-closed safety.

Crucial Constraints:

The shared profile/config model is a schema / library, not a shared credential pool.
Tokens remain service-local; profiles are per service.
Orchestrators must not directly hold every service credential.

2. Profile Schema (Per Service)

The schema reuses the proven Gitea field model, adapted per service.

{
  "profile_name": "readonly-metrics",
  "service": "glitchtip",
  "token_source_name": "GLITCHTIP_API_TOKEN_READONLY",
  "allowed_operations": [
    "glitchtip.event.read",
    "glitchtip.issue.read"
  ],
  "forbidden_operations": [
    "glitchtip.issue.resolve",
    "glitchtip.issue.delete"
  ]
}

Schema Rules

allowed_operations are namespaced (e.g., gitea.issue.create, jenkins.build.read, glitchtip.event.read).
forbidden_operations, if present, always override allowed_operations.
token_source_name records the source name only, never the value. Tokens must never be printed, logged, or included in telemetry.

3. Fail-Closed Behavior

The model enforces strict fail-closed constraints before any network call occurs:

Missing Profile: If a requested profile is undefined for the target service, the operation fails immediately.
Missing Credentials: If the token_source_name cannot be resolved to a valid token at runtime, the operation fails immediately without retrying or prompting.

4. Environment Overrides

Profiles can be dynamically overridden or injected via environment variables, following the established hierarchy:

Explicit Environment Variable: (Highest precedence) e.g., MCP_GLITCHTIP_TOKEN overrides any JSON profile.
Profile Mapping in JSON: Resolved via token_source_name (e.g., GLITCHTIP_API_TOKEN_READONLY) mapping to an environment variable or secret store.
No Auth: Fails closed.

5. Audit Logging

To maintain accountability across multi-service workflows, all mutating actions must include the audit identity and source:

The audit log must record the profile_name, the orchestrator source (e.g., sysadmin, jenkins-mcp), and the action taken.
The audit system must sanitize all output to ensure tokens are stripped (see safety-model.md).

6. Backward Compatibility

The existing Gitea profile behavior (gitea_whoami, etc.) remains strictly backward compatible. The generic profile library will parse existing Gitea profile objects without requiring them to migrate their schemas, defaulting the service attribute to gitea.

7. Implementation Boundary

Per the namespace decisions in #71 and #75, this generic model belongs in the common package or library. It will be imported by gitea-mcp (this repo), jenkins-mcp, and glitchtip-mcp without forcing a monolithic architecture.

3.2 KiB Raw Blame History