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-only build/job inspection
glitchtip-mcp	GlitchTip observability inspection	Read-only issue/event inspection

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 tools:

• jenkins_whoami
• jenkins_list_jobs
• jenkins_latest_build
• jenkins_build_status
• jenkins_get_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.
• Jenkins build triggers require a separately named write profile, exact confirmation, and fail-closed mutation audit.
• glitchtip-mcp remains read-only. It must not file or mutate Gitea issues.
• GlitchTip-to-Gitea filing is a separate orchestrator that composes GlitchTip read tools with Gitea issue-write tools.
• Gitea credentials never enter Jenkins or GlitchTip runtimes.
• Jenkins and GlitchTip credentials never enter the Gitea MCP runtime.