Thinking Path

• Paperclip manages AI agents and their tool connections.
• Remote MCP tools use the credentials declared by each connection.
• A connection can declare a required header credential that the caller's grant does not contain.
• The gateway currently skips that missing grant reference and sends the request without the header.
• This pull request reports the missing credential and stops the request before dispatch.
• This keeps the failure local and prevents an unauthenticated call to the remote server.

Linked Issues or Issue Description

Fixes: #17059
Refs: #15425 (related secret-resolution failure; this change handles a missing grant reference).
Related PRs: #13479 (shared remote MCP headers) and #15192 (OAuth client credentials). This change handles only a required grant reference that is absent.

What Changed

• Return 422 mcp_remote_missing_secret and mark the connection missing_secret when a required header credential has no matching grant reference.
• Add a fake-server regression test that confirms the request is not sent.

Verification

• pnpm exec vitest run --project @paperclipai/server server/src/__tests__/tool-gateway.test.ts — passed (92 tests).
• pnpm --filter @paperclipai/server exec tsc --noEmit — passed.
• git diff --check — passed.
• The server typecheck script was also attempted. Its Runner build preflight stopped because this host has Rust 1.85.1 and the locked dependencies require Rust 1.94.1. The direct server TypeScript check passed.

Risks

Low risk. Calls with a valid grant are unchanged. A missing required credential now fails before network dispatch.

Model Used

OpenAI GPT-6 via Codex. The runtime does not expose the context-window size. Tool use and local code execution were used.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have linked the existing issue with Fixes: #17059
• I have not referenced internal/instance-local Paperclip issues or links
• My branch name describes the change and contains no internal issue id
• I have run the focused tests locally and they pass
• I have added a regression test
• I have considered and documented the risk
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge