Skip to content

Document vMCP embedded auth server and upstream token injection #643

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

Merged
tgrunnagle merged 9 commits into from
Apr 7, 2026
Merged

Document vMCP embedded auth server and upstream token injection #643

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
abfa020
Add Redis Sentinel session storage guide and TLS docs
jhrozek Mar 10, 2026
bc0e5f4
Address PR feedback: fix placeholder and remove redirect
jhrozek Mar 12, 2026
b6e08be
Document vMCP embedded auth server and upstream token injection
jhrozek Mar 27, 2026
9d913fe
Minor updates
tgrunnagle Mar 31, 2026
7f7a9ba
Address feedback
tgrunnagle Mar 31, 2026
e3889e6
Resolve conflicts
tgrunnagle Mar 31, 2026
dca8035
Extract embedded auth server concept page
tgrunnagle Apr 3, 2026
6a8cf66
Address feedback
tgrunnagle Apr 3, 2026
b6a9fe2
Small tweak
tgrunnagle Apr 3, 2026
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
20 changes: 6 additions & 14 deletions docs/toolhive/concepts/backend-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,20 +211,10 @@ deployments using the ToolHive Operator.
- **Direct upstream redirect:** The embedded authorization server redirects
clients directly to the upstream provider for authentication (for example,
GitHub or Atlassian).
- **Single upstream provider:** Currently supports one upstream identity
provider per configuration.

:::info[Chained authentication not yet supported]

The embedded authorization server redirects clients directly to the upstream
provider. This means the upstream provider must be the service whose API the MCP
server calls. Chained authentication—where a client authenticates with a
corporate IdP like Okta, which then federates to an external provider like
GitHub—is not yet supported. If your deployment requires this pattern, consider
using [token exchange](#same-idp-with-token-exchange) with a federated identity
provider instead.

:::
- **Single upstream provider per MCPServer:** Individual MCPServer resources
support one upstream identity provider per configuration. For multiple
upstream providers with sequential authorization chaining, use a
[VirtualMCPServer with the embedded auth server](../guides-vmcp/authentication.mdx#embedded-authorization-server).

#### Token storage and forwarding

Expand Down Expand Up @@ -297,6 +287,8 @@ For the client-facing OAuth flow, see
[Embedded authorization server](./auth-framework.mdx#embedded-authorization-server).
For Kubernetes setup instructions, see
[Set up embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication).
For multi-upstream provider support with vMCP, see
[vMCP embedded authorization server](../guides-vmcp/authentication.mdx#embedded-authorization-server).

## Token exchange in depth

Expand Down
12 changes: 11 additions & 1 deletion docs/toolhive/concepts/vmcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ pre-configured tools with sensible defaults.

## Core value propositions

vMCP delivers four key benefits:
vMCP delivers five key benefits:

@jerm-dro jerm-dro Apr 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: The paragraph added below elaborates on benefit #2 (authentication boundary separation) rather than introducing a distinct fifth benefit. The original four — reduce complexity, simplify auth, secure by default, unified management — are still the four listed. Consider reverting this to "four key benefits" or restructuring the list if the embedded auth server really is a separate value prop.

@tgrunnagle tgrunnagle Apr 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to be a fix since there were already five benefits listed


1. **Reduce complexity**: Many connections become one, dramatically simplifying
configuration
Expand Down Expand Up @@ -136,6 +136,16 @@ your identity provider and all backend access is revoked instantly.
This approach provides single sign-on for users, centralized access control, and
a complete audit trail.

vMCP can also run an embedded authorization server that handles the full OAuth
flow with multiple upstream identity providers (such as GitHub, Google, or
Okta). This enables per-user backend authentication: when a user logs in, the
auth server acquires tokens from each upstream provider and injects them into
requests to the appropriate backends. MCP clients register automatically through
Dynamic Client Registration (DCR), so no manual client configuration is needed.
See
[Authentication](../guides-vmcp/authentication.mdx#embedded-authorization-server)
for setup details.

## When to use vMCP

### Good fit
Expand Down
2 changes: 2 additions & 0 deletions docs/toolhive/guides-k8s/auth-k8s.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -773,6 +773,8 @@ kubectl logs -n toolhive-system -l app.kubernetes.io/name=weather-server-k8s
[Authentication and authorization framework](../concepts/auth-framework.mdx)
- For conceptual background on the embedded authorization server, see
[Embedded authorization server](../concepts/auth-framework.mdx#embedded-authorization-server)
- For multi-upstream provider support with vMCP, see
[vMCP embedded authorization server](../guides-vmcp/authentication.mdx#embedded-authorization-server)
- For a similar configuration pattern using token exchange, see
[Configure token exchange](./token-exchange-k8s.mdx)
- For detailed Cedar policy syntax, see
Expand Down
4 changes: 3 additions & 1 deletion docs/toolhive/guides-k8s/redis-session-storage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,9 @@ spec:
```

The next section deploys a three-node Sentinel cluster that monitors the Redis
master and handles automatic failover:
master. With a single master and no replicas, Sentinel provides master discovery
for ToolHive but cannot perform automatic failover. To enable failover, add
Redis replicas to the StatefulSet and configure replication.

```yaml title="redis-sentinel.yaml — Sentinel cluster (append to same file)"
# --- Sentinel configuration
Expand Down
Loading