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

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