[github-actions]

kagent-dev/kagent#3257 — feat: add token passthrough for remote MCP servers

Docs versions: 1.x (first shipped in v1.0.0-alpha15)

No code-path rule covers 7 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/credential-injection.md
• go/api/gen/kagent/config/v1/adk.pb.go
• go/harness/codex/README.md
• proto/kagent/config/v1/adk.proto
• python/packages/kagent-adk/src/kagent/adk/types.py
• python/packages/kagent-proto/src/kagent/config/v1/adk_pb2.py
• ...and 1 more

What changes for users: RemoteMCPServer can set spec.tokenPassthrough: true to send the incoming A2A bearer token to the MCP server as Authorization: Bearer <token>. Requests without a caller token fail, and the API server rejects a RemoteMCPServer that combines tokenPassthrough with an Authorization entry in headersFrom. ModelConfig apiKeyPassthrough is renamed to tokenPassthrough.

What the docs now say: Your first MCP tool now shows a complete RemoteMCPServer example for caller-token authentication, including the discovery label and the headersFrom conflict. Agent harness now states that codex and claude reject RemoteMCPServer tokenPassthrough.

Not verified: No cluster; the configuration and commands are unrun.

How kagent-3257 was drafted, and what was not verified

• Code PR: feat: add token passthrough for remote MCP servers kagent#3257
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x; first shipped in v1.0.0-alpha15
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add RemoteMCPServer tokenPassthrough to the MCP tool documentation and note harness restrictions.
• Learned: Target model-provider pages already document the ModelConfig rename from apiKeyPassthrough to tokenPassthrough, from the target copies and the dossier grep.
• Did: Documented RemoteMCPServer caller-token passthrough in your-first-mcp-tool.md and added the codex/claude restriction to agent-harness.md.

Why a documentation change is necessary

The pull request adds RemoteMCPServer.spec.tokenPassthrough and a validation rule that rejects headersFrom entries named Authorization when passthrough is enabled. The existing MCP task guide shows how to create a RemoteMCPServer, but it did not show this authentication path or the discovery label that the pull request body says servers that require a caller token should set. The existing harness page listed MCP restrictions for codex and claude, but not the new passthrough rejection.

What changed on disk

• docs-site/content/kagent/1.x/get-started/your-first-mcp-tool.md: Added a caller-token RemoteMCPServer example, field table, and harness caveat.
• docs-site/content/kagent/1.x/agents/agent-harness.md: Added RemoteMCPServer tokenPassthrough to the codex and claude tool restrictions.

How to verify this change

1. Apply the RemoteMCPServer example from the new section with server-side dry run. The API server should accept spec.tokenPassthrough: true and the kagent.dev/discovery: disabled label.
2. Apply the same RemoteMCPServer with an Authorization entry in spec.headersFrom. The API server should reject it with headersFrom cannot set Authorization when tokenPassthrough is enabled.
3. Bind the RemoteMCPServer to an AgentTemplate and invoke the Agent through an A2A request that includes a bearer token. The MCP server should receive Authorization: Bearer <caller token> on its request.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false for this repository. Suggested note: Remote MCP servers can now set spec.tokenPassthrough to forward the caller's A2A bearer token as the server's Authorization header. ModelConfig spec.apiKeyPassthrough is renamed to spec.tokenPassthrough.

What was not verified

• The RemoteMCPServer configuration was not applied to a cluster, so every command in this diff is unrun.
• The runtime A2A invocation with a caller token was not run; the dossier did not include a concrete A2A client command for sending that token.
• Neighbor feat: support gateway token passthrough for embedded controllers kagent#3263 omitted some hunk details to stay under its size cap. No behavior from the omitted hunks was documented.

How the pages were chosen (triage report)

Feature clusters

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• feat: add token passthrough for remote MCP servers kagent#3257 and feat: Send PDF and Office files to Responses API models end-to-end kagent#3200 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there

Draft a documentation change

kagent-dev/kagent#3257 — feat: add token passthrough for remote MCP servers

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Minimal alternative to eitan/remote-mcp-token-passthrough. It contains only the passthrough feature and the API rename.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 7 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/credential-injection.md
  • go/api/gen/kagent/config/v1/adk.pb.go
  • go/harness/codex/README.md
  • proto/kagent/config/v1/adk.proto
  • python/packages/kagent-adk/src/kagent/adk/types.py
  • python/packages/kagent-proto/src/kagent/config/v1/adk_pb2.py
  • ...and 1 more

Draft branch: pr-tracker-draft-kagent-3257