Skip to content

Commit 26eff6b

Browse files
jhrozekclaude
andcommitted
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>
1 parent d367f0f commit 26eff6b

File tree

1 file changed

+18
-10
lines changed

1 file changed

+18
-10
lines changed

docs/toolhive/guides-vmcp/authentication.mdx

Lines changed: 18 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)"]
23+
Authz["Authorization<br>(Cedar policies)"]
24+
Proxy[Backend proxy]
25+
Auth --> Authz --> Proxy
2326
end
2427
2528
subgraph Boundary2[" "]
@@ -30,19 +33,24 @@ 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 — checking issuer, audience, expiry, and signature
44+
for JWTs, or using token introspection for opaque tokens — and 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. The audience value must be explicitly set in
48+
`incomingAuth` (see [OIDC authentication](#oidc-authentication) below).
49+
50+
**Boundary 2 (Outgoing):** vMCP obtains credentials for each backend API using
51+
the configured outgoing auth strategy. See
52+
[Outgoing authentication](#outgoing-authentication) for the available
53+
strategies.
4654

4755
## Incoming authentication
4856

0 commit comments

Comments
 (0)