Skip to content

Commit f19c445

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #109621 from ShaunaDiaz/OSDOCS-18938
OSDOCS-18938: adds creating virt servers to MCP gateway docs
2 parents 4b7c6f0 + 35835ba commit f19c445

8 files changed

Lines changed: 297 additions & 1 deletion

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ Topics:
7777
File: mcp-gateway-register-on-prem-mcp-servers
7878
- Name: Registering external MCP servers
7979
File: mcp-gateway-register-ext-mcp-servers
80+
- Name: Creating virtual MCP servers
81+
File: mcp-gateway-creating-virtual-mcp-servers
8082
- Name: Configuring authentication for the MCP gateway
8183
File: mcp-gateway-authentication
8284
- Name: Configuring authorization for the MCP gateway

‎mcp_gateway_config/mcp-gateway-creating-virtual-mcp-servers.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="mcp-gateway-create-virtual-mcp-servers"]
3+
= Creating virtual MCP servers
4+
include::_attributes/attributes.adoc[]
5+
:context: mcp-gateway-register-virtual-mcp-servers
6+
7+
[role="_abstract"]
8+
Create focused, curated tool collections from your aggregated internal and external MCP servers by creating virtual MCP servers from any of your registered MCP servers.
9+
10+
include::modules/con-register-virt-mcp-server.adoc[leveloffset=+1]
11+
12+
include::modules/con-virt-mcp-server-auth-tool-filtering.adoc[leveloffset=+1]
13+
14+
include::modules/proc-mcp-gateway-create-virt-mcp-server.adoc[leveloffset=+1]
15+
16+
include::modules/proc-verify-virt-mcp-server.adoc[leveloffset=+1]
17+
18+
include::modules/proc-mcp-gateway-delete-virtual-server.adoc[leveloffset=+1]

‎mcp_gateway_config/mcp-gateway-register-on-prem-mcp-servers.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
[id="mcp-gateway-register-on-prem-mcp-servers"]
33
= Registering on-prem MCP servers
44
include::_attributes/attributes.adoc[]
5-
:context: mcp-gateway-register-servers
5+
:context: mcp-gateway-register-on-prem-servers
66

77
[role="_abstract"]
88
To begin using MCP servers with your {mcpg}, you must register each server by creating an `HTTPRoute` custom resource (CR) and a corresponding `MCPServerRegistration` CR that references the route.

‎modules/con-register-virt-mcp-server.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// *mcp_gateway_config/mcp-gateway-register-virtual-mcp-servers.adoc
5+
6+
:_mod-docs-content-type: CONCEPT
7+
[id="con-create-virt-mcp-server_{context}"]
8+
= About virtual MCP servers
9+
10+
[role="_abstract"]
11+
When you aggregate all your MCP servers centrally, you solve for authentication, authorization, and configuration management. At the same time, this aggregation can overwhelm large-language models (LLMs) and AI agents with too many tool choices. You can create virtual MCP servers to curate tools for each situation.
12+
13+
You can narrow the scope for your agentic services and applications by creating virtual MCP servers that filter the complete tool list based on a curated selection and access only the relevant tools with HTTP headers. You can use virtual MCP servers to accomplish the following efficiencies:
14+
15+
* Create specialized collections of tools for specific use cases.
16+
* Reduce the load on LLMs by presenting fewer, more relevant tools.
17+
* Group tools by function, for example, development tools, data analysis tools, and so on.
18+
* Make it easier for users and agents to find the right tools.
19+
* Combine with authorization policies for fine-grained access management.
20+
21+
Virtual MCP servers only filter which tools a client can discover by using the `tools/list` concept. Virtual MCP servers do not change `tools/call` routing or authorization.

‎modules/con-virt-mcp-server-auth-tool-filtering.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-virtual-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="con-virt-mcp-server-auth-tool-filtering_{context}"]
7+
= About virtual MCP servers authorization and tool filtering
8+
9+
[role="_abstract"]
10+
If you have authentication and user-based tool filtering configured on your MCP servers, and then set up virtual MCP servers, the resulting tool list is the intersection of two filters.
11+
12+
The `AuthPolicy` custom resource (CR) configurations you applied when you registered the MCP servers are used. You do not need to make additional configurations when creating virtual MCP servers.
13+
14+
The MCP gateway broker component applies filters sequentially when handling a `tools/list` request with a virtual MCP server header. The following are the applied filters in order:
15+
16+
. Identity-based filtering: The `x-authorized-tools` header, injected by the `AuthPolicy` CR, reduces the tool list to only the tools that the user has `resource_access` roles configured for.
17+
. Virtual MCP server filtering: The `X-Mcp-Virtualserver` header further reduces the available-tools list to only those tools that are defined in the `MCPVirtualServer` CR.
18+
19+
For example, if the `accounting` virtual server lists `test1_greet` and `test3_add`, but the user only has the `greet` role on `mcp-test/test-server1`, that user only sees the tool, `test1_greet`.

‎modules/proc-mcp-gateway-create-virt-mcp-server.adoc‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-create-virtual-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-mcp-gateway-create-virt-mcp-server_{context}"]
7+
= Creating virtual MCP servers
8+
9+
[role="_abstract"]
10+
To create virtual MCP servers for different use cases, you must define the virtual server with an `MCPVirtualServer` custom resource (CR) that specifies required fields. When a client includes the virtual MCP server header, the MCP gateway filters responses to only include the specified tools.
11+
12+
An `MCPVirtualServer` CR must contain the following information:
13+
14+
* Tool selection: Which tools from the aggregated pool to expose.
15+
* Description: A human-readable description of the virtual MCP server's purpose.
16+
* Access method: Tools are accessed by the `X-Mcp-Virtualserver` header with the `namespace/name` format.
17+
18+
.Prerequisites
19+
20+
* You completed all of the installation and configuration steps for {mcpg}.
21+
* You registered your MCP servers.
22+
* You installed the {oc-first}.
23+
24+
.Procedure
25+
26+
. Create an `MCPVirtualServer` CR for a virtual MCP server that curates development tools by using the following example:
27+
+
28+
.Example developer tools MCPVirtualServer CR
29+
[source,yaml,subs="+quotes"]
30+
----
31+
apiVersion: mcp.kuadrant.io/v1alpha1
32+
kind: MCPVirtualServer
33+
metadata:
34+
name: _<dev_tools>_
35+
namespace: _<mcp_system>_
36+
spec:
37+
description: "Development and debugging tools"
38+
tools:
39+
- mcpserver1_devtool1
40+
- mcpserver2_headers1
41+
- mcpserver3_debug1
42+
----
43+
+
44+
* Replace the `metadata.name:` value with the name you want to use.
45+
* Replace the `metadata.namespace:` value with the name you want to use.
46+
* Replace the list values in the `spec.tools:` parameter with the names of the tools you want to curate to this CR.
47+
48+
. Apply the CR by running the following command:
49+
+
50+
[source,terminal,subs="+quotes"]
51+
----
52+
$ oc apply -f _<mcpvs_devtools.yaml>_
53+
----
54+
+
55+
Replace `_<mcpvs_devtools.yaml>_` with the name of your CR.
56+
57+
. Create an `MCPVirtualServer` CR for a virtual server that curates data analysis tools by using the following example:
58+
+
59+
.Example data analysis tools MCPVirtualServer CR
60+
[source,yaml,subs="+quotes"]
61+
----
62+
apiVersion: mcp.kuadrant.io/v1alpha1
63+
kind: MCPVirtualServer
64+
metadata:
65+
name: _<data_tools>_
66+
namespace: _<mcp_system>_
67+
spec:
68+
description: "Data analysis and reporting tools"
69+
tools:
70+
- mcpserver2_time
71+
- mcpserver2_dozen
72+
- mcpserver1_get_stats
73+
----
74+
+
75+
* Replace the `metadata.name:` value with the name you want to use.
76+
* Replace the `metadata.namespace:` value with the namespace you want to use. The `metadata.namespace:` value can be any namespace where you have permission to create resources.
77+
* Replace the list values in `spec.tools:` with the names of the tools you want to curate to this CR.
78+
79+
. Apply the CR by running the following command:
80+
+
81+
[source,terminal,subs="+quotes"]
82+
----
83+
$ oc apply -f _<mcpvs_datatools.yaml>_
84+
----
85+
+
86+
Replace `_<mcpvs_datatools.yaml>_` with the name of your CR.
87+
88+
.Next step
89+
90+
* Verify that your virtual MCP servers are returning the tools you expect to see by following the instructions in "Verifying virtual MCP servers".

‎modules/proc-mcp-gateway-delete-virtual-server.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-create-virtual-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-mcp-gateway-delete-virt-mcp-server_{context}"]
7+
= Deleting virtual MCP servers
8+
9+
[role="_abstract"]
10+
You can delete a virtual MCP server when you no longer need it or when your MCP servers change.
11+
12+
.Prerequisites
13+
14+
* You completed all of the installation and configuration steps for {mcpg}.
15+
* You registered your MCP servers.
16+
* You installed the {oc-first}.
17+
* You created a virtual MCP server.
18+
19+
.Procedure
20+
21+
* Delete a virtual MCP server by running the following command:
22+
+
23+
[source,terminal,subs="+quotes"]
24+
----
25+
$ oc delete mcpvirtualserver _<dev_tools>_ -n _<mcp_system>_
26+
----
27+
+
28+
* Replace `_<dev_tools>_` with the name of the `MCPVirtualServer` custom resource you want to remove.
29+
* Replace `_<mcp_system>_` with the namespace where the CR is applied.

‎modules/proc-verify-virt-mcp-server.adoc‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-virtual-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-verify-virt-mcp-server_{context}"]
7+
= Verifying virtual MCP servers
8+
9+
[role="_abstract"]
10+
After you create your virtual MCP servers, you can check that they are returning the tool lists that you want.
11+
12+
.Prerequisites
13+
14+
* You completed all of the installation and configuration steps for {mcpg}.
15+
* You registered your MCP servers.
16+
* You installed the {oc-first}.
17+
* You applied `MCPVirtualServer` custom resource (CRs) for your virtual servers.
18+
19+
.Procedure
20+
21+
. List all of your virtual MCP servers by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc get mcpvirtualserver -A
26+
----
27+
+
28+
The expected output is a list of all of the virtual MCP servers that you created.
29+
30+
. Performs a connectivity and handshake test of your virtual `dev_tools` MCP server by running the following `curl` command with the relevant URL and header:
31+
+
32+
[source,terminal,subs="+quotes"]
33+
----
34+
$ curl -s -D /tmp/mcp_headers -X POST _<http:example.com:port/mcp>_ \
35+
-H "Content-Type: application/json" \
36+
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'
37+
----
38+
+
39+
* Replace `_<http:example.com:port/mcp>_` with the target URL and MCP gateway endpoint.
40+
+
41+
.Example output
42+
[source,json]
43+
----
44+
{
45+
"jsonrpc": "2.0",
46+
"id": 1,
47+
"result": {
48+
"protocolVersion": "2025-11-25",
49+
"capabilities": {
50+
"tools": {},
51+
"prompts": {},
52+
"resources": {}
53+
},
54+
"serverInfo": {
55+
"name": "mcp-gateway-server",
56+
"version": "1.0.0"
57+
}
58+
}
59+
}
60+
----
61+
62+
. Extract the MCP session ID from response headers by running the following command:
63+
+
64+
[source,terminal]
65+
----
66+
$ SESSION_ID=$(grep -i "mcp-session-id:" /tmp/mcp_headers | cut -d' ' -f2 | tr -d '\r')
67+
----
68+
+
69+
.Expected output
70+
[source,text]
71+
----
72+
echo "MCP Session ID: $SESSION_ID"
73+
----
74+
75+
. Request the tools from the `dev_tools` virtual MCP server by running the following command:
76+
+
77+
[source,terminal,subs="+quotes"]
78+
----
79+
$ curl -X POST _<http:example.com:port/mcp>_ \
80+
-H "Content-Type: application/json" \
81+
-H "mcp-session-id: $SESSION_ID" \
82+
-H "X-Mcp-Virtualserver: _<mcp_system>_/_<dev_tools>_" \
83+
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | jq '.result.tools[].name'
84+
----
85+
+
86+
* Replace `_<http:example.com:port/mcp>_` with the target URL and MCP gateway endpoint.
87+
* Replace `_<mcp_system>_` with the namespace of the MCP gateway.
88+
* Replace `_<dev_tools>_` with the tool headers that you want to request.
89+
* The expected response is a list of only the tools you specified in the `dev_tools` virtual MCP server specification.
90+
91+
. Request the tools from the `data_tools` virtual MCP server by running the following command:
92+
+
93+
[source,terminal,subs="+quotes"]
94+
----
95+
$ curl -X POST _<http:example.com:port>_/mcp \
96+
-H "Content-Type: application/json" \
97+
-H "mcp-session-id: $SESSION_ID" \
98+
-H "X-Mcp-Virtualserver: _<mcp_system>_/_<data_tools>_" \
99+
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | jq '.result.tools[].name'
100+
----
101+
+
102+
* Replace `_<http:example.com:port/mcp>_` with the target URL and MCP gateway endpoint.
103+
* Replace `_<mcp_system>_` with the namespace of the MCP gateway.
104+
* Replace `_<data_tools>_` with the tool headers that you want to request.
105+
* The expected response is a list of only the tools you specified in the `data_tools` virtual MCP server specification.
106+
107+
. Request all available tools from your MCP servers by running the following command:
108+
+
109+
[source,terminal,subs="+quotes"]
110+
----
111+
$ curl -X POST _<http:example.com:port>_/mcp \
112+
-H "mcp-session-id: $SESSION_ID" \
113+
-H "Content-Type: application/json" \
114+
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | jq '.result.tools[].name'
115+
----
116+
+
117+
The expected response is a list of all tools from all registered MCP servers.

0 commit comments

Comments
 (0)