Gitea-Tools/docs/mcp-client-registration.md

MCP Client Registration for External Control Plane Servers

Issue #151 fixes the registration and naming contract for the Jenkins and GlitchTip MCP servers that live outside this Gitea MCP runtime.

Canonical Server Names

Use these exact MCP server names in clients:

Server name	Boundary	Default capability
jenkins-mcp	Jenkins CI inspection (read)	Read-only build/job inspection
jenkins-write-mcp	Jenkins build trigger (write)	Gated jenkins_trigger_build only
glitchtip-mcp	GlitchTip observability inspection	Read-only issue/event inspection

The write boundary (jenkins-write-mcp) is not registered by default (#152). It exposes a single mutating tool and requires operator approval of a dedicated trigger profile before any client config references it.

Historical names such as jenkins-readonly and glitchtip-readonly are descriptive profile labels only. They are not the canonical MCP server names unless an operator intentionally creates aliases and documents them.

Registration Pattern

Register each external server as its own MCP entry. Do not add Jenkins or GlitchTip credentials to the Gitea MCP server. Also, do not add Gitea write credentials to the GlitchTip server.

{
  "mcpServers": {
    "jenkins-mcp": {
      "command": "/path/to/mcp-control-plane/venv/bin/python3",
      "args": ["-m", "jenkins_mcp"],
      "env": {
        "JENKINS_MCP_CONFIG": "/path/to/mcp-control-plane/profiles.json",
        "JENKINS_MCP_PROFILE": "jenkins-readonly"
      }
    },
    "glitchtip-mcp": {
      "command": "/path/to/mcp-control-plane/venv/bin/python3",
      "args": ["-m", "glitchtip_mcp"],
      "env": {
        "GLITCHTIP_MCP_CONFIG": "/path/to/mcp-control-plane/profiles.json",
        "GLITCHTIP_MCP_PROFILE": "glitchtip-readonly"
      }
    }
  }
}

Client-specific wrappers may differ, but the server names, trust boundaries, and profile separation must remain the same. After adding or changing either entry, reconnect or reload the MCP client before claiming the tools are usable.

Discoverability Validation

Before using either server in a task, prove the expected tools are visible in the client. It is not enough for the config entry to exist.

Expected Jenkins read tools (jenkins-mcp only):

• jenkins_whoami
• jenkins_list_jobs
• jenkins_latest_build
• jenkins_build_status
• jenkins_get_build

jenkins_trigger_build must not appear on jenkins-mcp. When an operator explicitly enables the write boundary, the only expected tool on jenkins-write-mcp is jenkins_trigger_build.

Expected GlitchTip tools:

• glitchtip_whoami
• glitchtip_list_projects
• glitchtip_list_unresolved
• glitchtip_get_issue
• glitchtip_recent_events
• glitchtip_search

If a client reports the server as enabled but exposes no usable tools, report SKIPPED: server enabled but no usable tools visible, then stop. Do not fall back to shell commands, raw service APIs, or unrelated MCP servers.

Boundary Rules

• jenkins-mcp read profiles must not expose build trigger tools.
• Build triggers live on the separate jenkins-write-mcp server (jenkins_mcp.write_server), not on jenkins-mcp.
• Jenkins build triggers require a dedicated trigger profile with jenkins.build.trigger allowed, exact confirmation (TRIGGER BUILD <job-path>), and fail-closed mutation audit.
• Do not register jenkins-write-mcp until an operator approves a trigger profile; no shipped profile carries trigger capability by default.
• glitchtip-mcp remains read-only. It must not file or mutate Gitea issues.
• GlitchTip-to-Gitea filing is a separate library-only orchestrator in mcp-control-plane that composes the real GlitchTip read path with Gitea issue-write tools.
• The filing orchestrator must run GlitchTip/Gitea dedup before any Gitea create action, and its create/link/skip decisions must be covered by tests.
• The filing orchestrator must fail closed on mutation-audit failure before any Gitea create, link, or comment mutation.
• If filing is ever MCP-exposed, it must use a separate write-boundary server/profile. It must not be exposed by glitchtip-mcp.
• Gitea credentials never enter Jenkins or GlitchTip runtimes.
• Jenkins and GlitchTip credentials never enter the Gitea MCP runtime.