sysadminandClaude Opus 4.8
b4e04f4dfb
Document that build triggers live on the gated jenkins-write-mcp server, not the read-only jenkins-mcp surface. Add registration and safety-model cross-links plus doc tests that fail if trigger tools reappear on the read boundary. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# 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.
|