Skip to content

Commit edb954e

Browse files
crivetimihaicrivetimihai
authored
Merge pull request #77 from IBM/add-ui-concepts-page
Add UI concepts page
2 parents 24cce3b + 5bd7b6b commit edb954e

File tree

2 files changed

+135
-0
lines changed

2 files changed

+135
-0
lines changed

‎docs/docs/overview/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ nav:
22
- index.md
33
- features.md
44
- ui.md
5+
- ui-concepts.md

‎docs/docs/overview/ui-concepts.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Admin Console Concepts
2+
3+
> This guide introduces each major section of the Gateway Admin UI and how it connects to the Model Context Protocol (MCP).
4+
5+
---
6+
7+
## 🆕 Setting up a new MCP Server to federate to the gateway
8+
9+
???+ example "🔌 How do I expose an MCP server over SSE?"
10+
To federate a new MCP Server to your gateway, it must run over **Server-Sent Events (SSE)** so the gateway can communicate with it.
11+
12+
You can use [`supergateway`](https://www.npmjs.com/package/supergateway) to wrap any `stdio`-only MCP server and expose it over SSE. Here are example commands:
13+
14+
```bash
15+
npx -y supergateway --stdio "uvenv run mcp-server-git" --port 8001
16+
npx -y supergateway --stdio "uvenv run mcp_server_time -- --local-timezone=Europe/Dublin"
17+
```
18+
19+
✅ **Important:** The gateway must be able to reach the MCP server's network address.
20+
21+
If you're running services inside Docker (or other containerized environments), ensure networking is configured properly:
22+
- Use `host` networking when needed.
23+
- Expose ports to the host machine.
24+
- Make sure internal container IPs are reachable from the gateway.
25+
26+
27+
## 📦 Virtual Servers
28+
29+
> A virtual server is a logical wrapper that combines selected tools, resources, and prompts under one context-specific endpoint.
30+
31+
???+ info "🔗 What are Virtual Servers?"
32+
- A Virtual Server defines a project-specific toolset.
33+
- Each one is backed by a real SSE or STDIO interface.
34+
- You can activate/deactivate, view metrics, and invoke tools from this server.
35+
36+
<!-- ![Virtual Server GIF](./images/virtual-servers.gif) -->
37+
38+
---
39+
40+
## 🛠 Global Tools
41+
42+
> Tools are remote functions that an LLM can invoke, either via MCP or REST. Think of them like typed APIs with schemas and optional auth.
43+
44+
???+ example "⚙️ What do Tools represent?"
45+
- Integration Types: `MCP`, `REST`
46+
- Request Types: `STDIO`, `SSE`, `GET`, `POST`, etc.
47+
- Input Schema: JSON Schema defines valid input.
48+
- Supports Basic Auth, Bearer, or Custom headers.
49+
50+
<!-- ![Tools GIF](./images/tools.gif) -->
51+
52+
---
53+
54+
## 📁 Global Resources
55+
56+
> Resources expose read-only data like files, database rows, logs, or screenshots. LLMs can read this content through a URI.
57+
58+
???+ example "📖 How do Resources work?"
59+
- Text and Binary data supported.
60+
- Exposed via unique URI (`file:///`, `db://`, etc.).
61+
- Resources can be listed, templated, or subscribed to.
62+
63+
<!-- ![Resources GIF](./images/resources.gif) -->
64+
65+
---
66+
67+
## 🧾 Global Prompts
68+
69+
> Prompts are reusable message templates with arguments. They define system prompts, user instructions, or chainable inputs.
70+
71+
???+ info "🗒 What's in a Prompt?"
72+
- Each prompt has a name, template, and arguments.
73+
- Arguments are defined with name, description, and required status.
74+
- Used to enforce consistency across tool use or system messaging.
75+
76+
<!-- ![Prompts GIF](./images/prompts.gif) -->
77+
78+
---
79+
80+
## 🌐 Gateways (MCP Servers)
81+
82+
> Gateways are other MCP-compatible servers. When registered, their tools/resources/prompts become usable locally.
83+
84+
???+ example "🌉 What is a federated Gateway?"
85+
- Syncs public tools from a remote MCP server.
86+
- Peer tools show up in your catalog with `gateway_id`.
87+
- Can be toggled active/inactive.
88+
89+
<!-- ![Gateways GIF](./images/gateways.gif) -->
90+
91+
---
92+
93+
## 📂 Roots
94+
95+
> Roots define base folders for file-based resources. They control what files MCP clients can access from your local system.
96+
97+
???+ tip "📁 What are Roots used for?"
98+
- Restrict access to specific folders (`file:///workspace`)
99+
- Prevent tools from referencing outside their sandbox.
100+
- Deleting a root invalidates its associated resources.
101+
102+
<!-- ![Roots GIF](./images/roots.gif) -->
103+
104+
---
105+
106+
## 📈 Metrics
107+
108+
> Track tool calls, resource reads, prompt renders, and overall usage in one place.
109+
110+
???+ info "📊 What does the Metrics tab show?"
111+
- Overall executions by server/tool/prompt.
112+
- Latency, failure rate, and hot paths.
113+
- Top tools, resources, prompts, and servers.
114+
115+
<!-- ![Metrics GIF](./images/metrics.gif) -->
116+
117+
---
118+
119+
## 🧪 Version & Diagnostics
120+
121+
> The `/version` endpoint returns structured JSON diagnostics including system info, DB/Redis health, and Git SHA.
122+
123+
???+ example "🩺 What does the Version panel include?"
124+
- MCP protocol version and server metadata.
125+
- Live system metrics (CPU, memory).
126+
- Environment checks and service readiness.
127+
128+
<!-- ![Version GIF](./images/version.gif) -->
129+
130+
---
131+
132+
## 📚 Learn More
133+
134+
- 🔗 [MCP Specification](https://modelcontextprotocol.org/spec)

0 commit comments

Comments
 (0)