mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A named MCP gateway gives a client its assigned tools. Each gateway token has a list of allowed actions > - A native run token allows only `tools/list` and `tools/call` > - `initialize` always advertises the `tools`, `resources` and `prompts` capabilities, whatever the token allows > - A client that follows the advertised capabilities calls `resources/list` and `prompts/list`, and the gateway refuses both with 403 `gateway_token_action_denied` > - This pull request makes `initialize` advertise only the capabilities whose list action the token allows > - The benefit is that a client is not told to call methods that its token cannot use ## Linked Issues or Issue Description This continues #17688, which made the same change and was closed unmerged by its author on 2026-11-02 ("we are no longer contributing upstream"). That pull request reports that Claude Code requests every advertised capability at once, drops the HTTP connection after the first 403, and then has no gateway tools for the run. I did not reproduce the Claude Code part. The gateway part is below. I searched pull requests for "allowedActions tools/list", "gateway token allowed actions context tools", "paperclip_list_resources", "gatewayTokenAllowedActions", "gateway_token_action_denied", "MCP gateway capabilities resources prompts", "initialize capabilities token" and "named gateway token actions discovery", and issues for "paperclip_list_resources" and "gateway token allowedActions". Results: - #17688 (closed, not merged): this change. - #14427 (open): filters the four `paperclip_*` context tools in `tools/list` by the token's allowed actions. It does not change `initialize`, so the two pull requests do not overlap. They touch different handlers in server/src/routes/tool-gateway.ts. No issue matched. **What happened?** On master, the `initialize` handler in server/src/routes/tool-gateway.ts returns `capabilities: { tools: {}, resources: {}, prompts: {} }` for every token. For a token that allows only `tools/list` and `tools/call`, a `resources/list` call returns 403 with reason code `gateway_token_action_denied`. **Expected behavior** `initialize` advertises `tools`, `resources` or `prompts` only when the token allows `tools/list`, `resources/list` or `prompts/list`. A session with no token action list keeps all three. **Steps to reproduce** 1. Create a named gateway and a token with `allowedActions: ["tools/list", "tools/call"]`. 2. Send `initialize` with the token. On master the result advertises `resources` and `prompts`. 3. Send `resources/list` with the same token. The gateway returns 403 `gateway_token_action_denied`. **Paperclip version or commit** master at499712c68b. **Deployment mode** Any deployment whose MCP clients use named gateway tokens with restricted actions, including native runs. ## What Changed - server/src/routes/tool-gateway.ts: `initialize` reads the session that `initializeNamedGatewayProtocol` already returns, and advertises each capability only when the token may list it. - server/src/__tests__/tool-gateway.test.ts: a new test sends `initialize` with five tokens (tools only, tools and prompts, tools and resources, no list action, and no action list) and checks the exact capabilities. It also checks that the tools-only token gets 403 `gateway_token_action_denied` on `resources/list`. ## Verification At heade40a1f7d6e, run from server: ```sh pnpm exec vitest run src/__tests__/tool-gateway.test.ts src/__tests__/tool-access-service.test.ts src/__tests__/tool-gateway-discovery-http.test.ts src/__tests__/mcp-http.test.ts src/__tests__/public-mcp.test.ts src/__tests__/tool-grant-scope.test.ts ``` - With server/src/routes/tool-gateway.ts from master and the test file from this branch: 1 failed, 706 passed. The new test fails at its first assertion: the tools-only token gets the tools, resources and prompts capabilities, where the test expects only tools. - With this branch: 707 passed. - Typecheck: `pnpm --filter @paperclipai/server typecheck` reports 29 errors, the same 29 as unmodified master ("Cannot find module @paperclipai/plugin-sdk" in the sandbox provider plugin packages of my local install). None is in a touched file, and this pull request adds none. - The full upstream test suite runs in CI. I ran only the test files named above. ## Risks - Low risk. Only the `initialize` response changes, and only for tokens that cannot list resources or prompts. Those methods were already refused for such tokens. - A client that called `resources/read` or `prompts/get` without listing first no longer sees the capability advertised for a token that allows only the read or get action. ## Model Used - Claude, claude-opus-5-5, with tool use and terminal code execution. The route change follows #17688. ## 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 (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>