## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Native providers can receive only the semantic operations authorized
for one run.
> - Codex ACP consumes those operations through an MCP endpoint.
> - The endpoint must be private, authenticated, bounded, and
deterministic under retries.
> - It must not advertise runner-private operations or allow callers to
replace terminal-result schemas.
> - This pull request adds a provider-neutral loopback MCP bridge with
those controls.
## Linked Issues or Issue Description
**What would you like to improve?**
The runner has a run-scoped semantic catalog and dispatcher, but the
ACPX runtime needs a secure transport for that catalog. A generic local
MCP server could expose extra operations, accept ambiguous tool
definitions, or execute the same call twice after a retry.
**Why is this important?**
Semantic tool presence is part of the authorization boundary.
Undiscoverable operations must remain unavailable. Terminal completion
and blocked-result schemas must not be replaceable. Duplicate call
identities must be idempotent, and conflicting duplicates must fail
closed.
**Suggested approach**
Bind one MCP endpoint to `127.0.0.1` for each admitted runtime. Require
a random bearer secret. Compile the closed tool schemas before
listening. Keep private operations out of `tools/list`. Validate and
fingerprint each call before dispatch. Bound request size, result size,
time, and retained call identities. Abort active operations on timeout,
cancellation, or bridge close.
**Additional context**
#12401 is merged. This PR does not attach the bridge to ACPX, register a
provider, or change any server or direct-adapter behavior.
## What Changed
- Add a provider-neutral runner semantic MCP bridge bound only to IPv4
loopback.
- Require constant-time bearer authentication before MCP operations.
- Expose only the supplied public catalog plus fixed completion and
blocked-result tools.
- Keep runner-private operations callable by trusted extensions but
absent from discovery.
- Reject invalid names, duplicate definitions, public/private
collisions, and terminal schema replacement.
- Compile JSON Schema validators before accepting traffic.
- Validate calls before dispatch and replay identical duplicate
identities exactly once.
- Treat numeric and string JSON-RPC identities as distinct and reject
conflicting duplicates.
- Bound request bodies, result text, timeouts, retained identities, and
concurrent capacity.
- Terminate oversized request bodies, preserve successful mutation
outcomes, and keep complete semantic results.
- Propagate MCP cancellation and abort active calls during close.
## Verification
- Exact verified head: `e5070e235448680e480e8d3f66bb46ac62d71c8e`.
- Full GitHub PR workflow passed in [run
33342776925](https://github.com/paperclipai/paperclip/actions/runs/33342776925),
including runner verification/build, typecheck, all test shards, canary,
and e2e.
- Greptile is 5/5 on the exact head with zero unresolved review threads.
- Superagent Security, Snyk, contributor trust, and commitperclip passed
on the exact head.
- Storybook skipped by path as expected.
- The diff contains 2 files and does not change dependencies,
`pnpm-lock.yaml`, workflows, migrations, server selection, or UI
behavior.
- No additional local suite was run during the final restack; GitHub
Actions is the authoritative verification environment.
## Risks
The main risk is widening model-visible authority. The bridge exposes
only its closed public catalog and fixed terminal tools; private
operations are omitted from discovery and catalog ambiguity fails during
startup. Another risk is duplicate execution after a provider retry. The
bridge fingerprints each admitted JSON-RPC identity, reuses the first
promise for exact retries, and rejects changed payloads. The endpoint
uses loopback plus a per-runtime bearer secret and has no production
caller in this pull request.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used with version and capability
details
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have added or updated tests where applicable
- [x] I have documented the authorization, network, idempotency, and
rollout risks
- [x] All applicable GitHub Actions are green
- [x] Greptile is 5/5 with every actionable comment resolved
- [x] I have addressed all review findings before merge
9036d3c484