# 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.

```json
{
  "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 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.