Skip to content

Commit ea3af30

Browse files
jhrozekclaude
andauthored
Expand vMCP two-boundary auth diagram and descriptions (#681)
* Expand vMCP two-boundary auth diagram and descriptions - Show token validation, Cedar policy authz, and backend proxy as distinct steps inside the vMCP box - Clarify Boundary 1 covers issuer, audience, expiry, and signature (JWT) or introspection (opaque tokens) - Note that audience must be explicitly configured for vMCP, unlike plain MCPServer deployments - Replace incomplete outgoing strategy list with a link to the Outgoing authentication section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Address two Copilot review comments on PR #681 - Line 22: add signature/introspection to diagram token validation node to match prose description of JWT and opaque token paths - Line 48: replace inaccurate blanket audience requirement with accurate distinction: required for oidcConfigRef, optional for inline OIDC Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fixup! Expand vMCP two-boundary auth diagram and descriptions --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 2ee3a42 commit ea3af30

1 file changed

Lines changed: 20 additions & 10 deletions

File tree

docs/toolhive/guides-vmcp/authentication.mdx

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,11 @@ flowchart LR
1818
end
1919
2020
subgraph vMCP["Virtual MCP Server (vMCP)"]
21-
Auth[Token validation]
22-
Backend[Backend auth]
21+
direction TB
22+
Auth["Token validation<br>(issuer, audience, expiry,<br>signature/introspection)"]
23+
Authz["Authorization<br>(Cedar policies)"]
24+
Proxy[Backend proxy]
25+
Auth --> Authz --> Proxy
2326
end
2427
2528
subgraph Boundary2[" "]
@@ -30,19 +33,26 @@ flowchart LR
3033
end
3134
3235
Client -->|"vMCP-scoped<br>token"| Auth
33-
Auth --> Backend
34-
Backend -->|"Backend-scoped<br>token"| GitHub
35-
Backend -->|"Backend-scoped<br>token"| Jira
36+
Proxy -->|"Backend-scoped<br>token"| GitHub
37+
Proxy -->|"Backend-scoped<br>token"| Jira
3638
```
3739

3840
**Boundary 1 (Incoming):** Clients authenticate to vMCP using OAuth 2.1
3941
authorization as defined in the
4042
[MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
41-
This is your organization's identity layer.
42-
43-
**Boundary 2 (Outgoing):** vMCP obtains appropriate credentials for each
44-
backend. Each backend API receives a token or credential scoped to its
45-
requirements.
43+
The vMCP validates the token by checking issuer, audience, expiry, and signature
44+
for JWTs, or by using token introspection for opaque tokens. It then evaluates
45+
Cedar policies before forwarding the request. This all happens inside the single
46+
`vmcp` process, unlike a plain MCPServer deployment where a separate ToolHive
47+
proxy handles this step. When using shared OIDC configuration via
48+
`oidcConfigRef`, the audience value must be explicitly set. For inline OIDC
49+
configuration, it is optional but recommended. See
50+
[OIDC authentication](#oidc-authentication) below.
51+
52+
**Boundary 2 (Outgoing):** vMCP obtains credentials for each backend API using
53+
the configured outgoing auth strategy. See
54+
[Outgoing authentication](#outgoing-authentication) for the available
55+
strategies.
4656

4757
## Incoming authentication
4858

0 commit comments

Comments
 (0)