Skip to content

[Automated] Draft docs (kagent): feat: add token passthrough for remote MCP servers #646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[Automated] Draft docs (kagent): feat: add token passthrough for remote MCP servers #646

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs-site/content/kagent/1.x/agents/agent-harness.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,7 @@ The `kagent` harness accepts every AgentTemplate feature. Codex and Claude run a
| A subagent binding cannot itself carry tools, skills, plugins, or nested agents, and must use the same provider and credentials as the agent that binds it. | `codex`, `claude` |
| The agent sees every tool that an {{< gloss "MCP" >}}MCP{{< /gloss >}} server offers, because Claude does not support partial tool selection. A binding that names a subset of tools binds the whole server instead. The Agent still reconciles, and reports the decision in `status.warnings` as `Claude RemoteMCPServer "<name>" does not support partial tool selection`. | `claude` |
| A RemoteMCPServer must use the `STREAMABLE_HTTP` protocol. `SSE` is rejected. | `codex` |
| A RemoteMCPServer that sets `tokenPassthrough` is rejected. | `codex`, `claude` |
| Structured output is rejected, with `Harness runtime "<name>" does not support structured output`. | `codex`, `claude`, `byo` |

For more information about what an AgentTemplate can bind, see [About tools]({{< link path="skills-and-mcp/about-tools" >}}).
Expand Down
29 changes: 29 additions & 0 deletions docs-site/content/kagent/1.x/get-started/your-first-mcp-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,34 @@ A `RemoteMCPServer` points at any MCP server that the cluster can reach, whether

3. Create another Session to run the revision that includes the new binding.

### Use the caller token for MCP server authentication {#use-the-caller-token-for-mcp-server-authentication}

If your MCP server authorizes each user with the caller's bearer token, create a separate RemoteMCPServer with `tokenPassthrough: true`. With token passthrough, the server receives the token as its `Authorization` header. The MCP request fails when the agent invocation has no caller token.

```yaml
kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: RemoteMCPServer
metadata:
name: user-mcp-server
namespace: kagent
labels:
kagent.dev/discovery: disabled
spec:
description: An MCP server that authenticates each caller.
url: https://mcp.example.com/mcp
protocol: STREAMABLE_HTTP
tokenPassthrough: true
EOF
```

| Field | Description |
| ----- | ----------- |
| `metadata.labels.kagent.dev/discovery` | Set to `disabled` when the server requires a caller token to list tools. Controller discovery runs before a user request exists. |
| `tokenPassthrough` | Sends the caller's bearer token as `Authorization: Bearer <token>`. A RemoteMCPServer that sets `tokenPassthrough` cannot also set an `Authorization` header in `headersFrom`. |

The `codex` and `claude` harnesses reject a RemoteMCPServer that sets `tokenPassthrough`.

## Clean up

> [!IMPORTANT]
Expand All @@ -185,6 +213,7 @@ If you created a RemoteMCPServer of your own in [Bind your own MCP server](#bind

```bash
kubectl delete remotemcpserver my-mcp-server -n kagent
kubectl delete remotemcpserver user-mcp-server -n kagent
```

## Next steps
Expand Down