Central-tools MCP gateway for harnesses behind the egress proxy #222

Closed
opened 2026-10-27 13:35:27 +00:00 by sam · 2 comments
Owner

Serve the central tools a Kit profile's AllowTools permits to harness runs through a Streamable HTTP MCP gateway reachable only via the egress proxy. The proxy injects the run's gateway token on the outbound request, so the container holds only a sentinel, matching credential@1. The gateway scopes every call to the run credential's identity and the profile's AllowTools. Capture tools stay on the stdio archie-agent mcp; the workspace toolset is never served.

Includes the PRD edit: docs/prds/external-agent-harness.md 'Archie tools inside the harness' currently says archie-agent mcp serves the central tools too; move central tools to the gateway and add a Verification line (a harness calls a permitted central tool; the token never appears in the container; a tool outside AllowTools is refused).

Acceptance criteria

A harness can call an allowed central tool through the egress proxy; its gateway token stays out of the container, and calls outside AllowTools are refused.

Notes

Unblocked (2026-10-04): the egress proxy session is now keyed by the run credential (23636d61), so the gateway token can be injected per session and the gateway can resolve the run's identity with ResolveTaskGrant / TaskForCredential, as the forge RPC does.
Implementation committed 3f553bb6; Docker and real-CLI acceptance per adapter still outstanding; Pi registerMcpServer API unverified.


Imported from beads archie-core-egkf.12 · GitHub #1182 · type task · priority P1 · created 2026-09-26

Serve the central tools a Kit profile's AllowTools permits to harness runs through a Streamable HTTP MCP gateway reachable only via the egress proxy. The proxy injects the run's gateway token on the outbound request, so the container holds only a sentinel, matching credential@1. The gateway scopes every call to the run credential's identity and the profile's AllowTools. Capture tools stay on the stdio archie-agent mcp; the workspace toolset is never served. Includes the PRD edit: docs/prds/external-agent-harness.md 'Archie tools inside the harness' currently says archie-agent mcp serves the central tools too; move central tools to the gateway and add a Verification line (a harness calls a permitted central tool; the token never appears in the container; a tool outside AllowTools is refused). ### Acceptance criteria A harness can call an allowed central tool through the egress proxy; its gateway token stays out of the container, and calls outside AllowTools are refused. ### Notes Unblocked (2026-10-04): the egress proxy session is now keyed by the run credential (23636d61), so the gateway token can be injected per session and the gateway can resolve the run's identity with ResolveTaskGrant / TaskForCredential, as the forge RPC does. Implementation committed 3f553bb6; Docker and real-CLI acceptance per adapter still outstanding; Pi registerMcpServer API unverified. --- _Imported from beads `archie-core-egkf.12` · GitHub #1182 · type task · priority P1 · created 2026-09-26_
sam added the highin-progresstask labels 2026-10-27 13:35:27 +00:00
sam self-assigned this 2026-10-27 13:35:27 +00:00
Author
Owner

sam wrote (originally 2026-10-02):

Triage 2026-10-02 @ 11974196: NOT STARTED. No MCP gateway of any kind exists. internal/tools/mcp is client transports only; the sole MCP server is stdio and capture-only (agentexec/capture_mcp.go:45). The egress Session has no identity and no AllowTools (egress/proxy.go:38-42) and the relay forwards exactly three fixed ports (3128/4222/50051). The required PRD edit has not landed -- docs/prds/external-agent-harness.md:210-213 still says central tools are served by 'archie-agent mcp' (stdio), and the Verification section lacks the three required lines. Genuinely blocked by archie-core-cklk (there is no run credential to scope calls to) and by the partially-shipped egkf.11. Also needs a design decision: the approved PRD defines no MCP gateway, so token mint/lifetime/revocation, the identity claim, AllowTools attribution and the proxy route are all open.

_sam wrote (originally 2026-10-02):_ Triage 2026-10-02 @ 11974196: NOT STARTED. No MCP gateway of any kind exists. internal/tools/mcp is client transports only; the sole MCP server is stdio and capture-only (agentexec/capture_mcp.go:45). The egress Session has no identity and no AllowTools (egress/proxy.go:38-42) and the relay forwards exactly three fixed ports (3128/4222/50051). The required PRD edit has not landed -- docs/prds/external-agent-harness.md:210-213 still says central tools are served by 'archie-agent mcp' (stdio), and the Verification section lacks the three required lines. Genuinely blocked by archie-core-cklk (there is no run credential to scope calls to) and by the partially-shipped egkf.11. Also needs a design decision: the approved PRD defines no MCP gateway, so token mint/lifetime/revocation, the identity claim, AllowTools attribution and the proxy route are all open.
Author
Owner

Triaged: no code change is needed for this. The requested behaviour is already in the working tree, and the PRD edit the issue asks for is already written.

What exists (verified by reading the code):

  • Egress confinement: internal/infrastructure/egress/proxy.go serveTaskTools only serves the exact http://archie.tools/mcp endpoint, only in the task runtime phase, only for a session that has a run credential, and only when the request carries tasktools.Sentinel; it then replaces that header with the host-held s.gatewayToken and deletes Proxy-Authorization. The token is generated per session (proxy.go:186) and calls are cancelled on session revocation.
  • Gateway scoping: internal/app/archiegateway/task_tools.go resolves the task/identity/org from the run credential on every ListTaskTools/CallTaskTool (TaskPrincipalForCredential, PrincipalFor, org match, status must be running), and bounds the served set by storepkg.AllowedTools(profile.Tools, packaged, accepted) for the Kit profile in that task's workflow, intersected with the package's accepted authority. taskToolAllowed excludes the workspace toolset, send_file, and approval-required tools. A call outside the allowlist is PermissionDenied (findTaskTool miss), and authorization is re-checked per call, so a revoked grant cannot execute.
  • Harness side: internal/agentexec/harness_mcp.go addCentralTools has the stdio archie-agent mcp bridge connect to tasktools.Endpoint through HTTP_PROXY, sending only Bearer tasktools.Sentinel; launcher.go:295 sets Harness.CentralTools, archied/kit_launcher.go:75 supplies the gateway as the proxy's TaskTools backend, and per-adapter registration is in harnessMCPRegistration (Codex inline config, Pi extension, OMP .mcp.json, Claude/Copilot via {{.MCPConfig}}).
  • PRD: docs/prds/external-agent-harness.md "Archie tools inside the harness" already says capture tools stay on the stdio server and central-tool discovery/calls go over Streamable HTTP to http://archie.tools/mcp via the proxy, with the sentinel/gateway-token split, gateway-side grant resolution, AllowTools bounding and workspace exclusion. The "Verification" section already contains the three lines the issue asks to add (permitted tool called through the proxy, token never in the container/MCP files/worktree/logs, out-of-allowlist tool refused, permission change applied at next call).
  • Tests matching the acceptance criteria: internal/infrastructure/egress/task_tools_test.go (runtime allowed; install, setup, revoked, forged bearer, other host/path/port/query all refused; gateway token neither container-visible nor echoed) and internal/app/archiegateway/task_tools_test.go (TestTaskToolAuthorization, TestTaskToolGatewayThroughProxy: allowed; profile denial; package intersection; workspace/chat-file/approval never served; revoked; not running; other org; non-daemon caller; re-auth after discovery).

What remains is not code: Docker and real-CLI acceptance per adapter, and confirming Pi's published registerMcpServer(name, definition) signature (harness_mcp.go:46). The repo contains nothing showing that call is wrong, so I am not treating it as a defect; if the Pi API check fails, the fix would be to change that one adapter's registration in harnessMCPRegistration.

Not verified this run: I did not execute go test (read-only tooling, no shell), and no git history is present locally (.git/logs absent), so I cannot confirm the claimed commit 3f553bb6 — only that the code and PRD text exist in this tree.

Triaged: no code change is needed for this. The requested behaviour is already in the working tree, and the PRD edit the issue asks for is already written. What exists (verified by reading the code): - Egress confinement: `internal/infrastructure/egress/proxy.go` `serveTaskTools` only serves the exact `http://archie.tools/mcp` endpoint, only in the task `runtime` phase, only for a session that has a run credential, and only when the request carries `tasktools.Sentinel`; it then replaces that header with the host-held `s.gatewayToken` and deletes `Proxy-Authorization`. The token is generated per session (`proxy.go:186`) and calls are cancelled on session revocation. - Gateway scoping: `internal/app/archiegateway/task_tools.go` resolves the task/identity/org from the run credential on every `ListTaskTools`/`CallTaskTool` (`TaskPrincipalForCredential`, `PrincipalFor`, org match, status must be `running`), and bounds the served set by `storepkg.AllowedTools(profile.Tools, packaged, accepted)` for the Kit profile in that task's workflow, intersected with the package's accepted authority. `taskToolAllowed` excludes the `workspace` toolset, `send_file`, and approval-required tools. A call outside the allowlist is `PermissionDenied` (`findTaskTool` miss), and authorization is re-checked per call, so a revoked grant cannot execute. - Harness side: `internal/agentexec/harness_mcp.go` `addCentralTools` has the stdio `archie-agent mcp` bridge connect to `tasktools.Endpoint` through `HTTP_PROXY`, sending only `Bearer tasktools.Sentinel`; `launcher.go:295` sets `Harness.CentralTools`, `archied/kit_launcher.go:75` supplies the gateway as the proxy's `TaskTools` backend, and per-adapter registration is in `harnessMCPRegistration` (Codex inline config, Pi extension, OMP `.mcp.json`, Claude/Copilot via `{{.MCPConfig}}`). - PRD: `docs/prds/external-agent-harness.md` "Archie tools inside the harness" already says capture tools stay on the stdio server and central-tool discovery/calls go over Streamable HTTP to `http://archie.tools/mcp` via the proxy, with the sentinel/gateway-token split, gateway-side grant resolution, AllowTools bounding and workspace exclusion. The "Verification" section already contains the three lines the issue asks to add (permitted tool called through the proxy, token never in the container/MCP files/worktree/logs, out-of-allowlist tool refused, permission change applied at next call). - Tests matching the acceptance criteria: `internal/infrastructure/egress/task_tools_test.go` (runtime allowed; install, setup, revoked, forged bearer, other host/path/port/query all refused; gateway token neither container-visible nor echoed) and `internal/app/archiegateway/task_tools_test.go` (`TestTaskToolAuthorization`, `TestTaskToolGatewayThroughProxy`: allowed; profile denial; package intersection; workspace/chat-file/approval never served; revoked; not running; other org; non-daemon caller; re-auth after discovery). What remains is not code: Docker and real-CLI acceptance per adapter, and confirming Pi's published `registerMcpServer(name, definition)` signature (`harness_mcp.go:46`). The repo contains nothing showing that call is wrong, so I am not treating it as a defect; if the Pi API check fails, the fix would be to change that one adapter's registration in `harnessMCPRegistration`. Not verified this run: I did not execute `go test` (read-only tooling, no shell), and no git history is present locally (`.git/logs` absent), so I cannot confirm the claimed commit 3f553bb6 — only that the code and PRD text exist in this tree.
sam closed this issue 2026-11-08 22:03:34 +00:00
sam added a new dependency 2026-11-14 14:45:13 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#222