Skip to content

Commit 18e6b9a

Browse files
danbarrdanbarr
committed
Add initial MCP usage guides
Signed-off-by: Dan Barr <[email protected]>
1 parent 984f6d8 commit 18e6b9a

File tree

13 files changed

+1397
-0
lines changed

13 files changed

+1397
-0
lines changed

‎docs/toolhive/guides-mcp/_template.mdx‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: SERVER_NAME MCP server guide
3+
sidebar_label: SERVER_NAME
4+
description: Using the SERVER_NAME MCP server with ToolHive for PURPOSE.
5+
last_update:
6+
author: YOUR_GITHUB_USERNAME
7+
date: YYYY-MM-DD
8+
---
9+
10+
import Tabs from '@theme/Tabs';
11+
import TabItem from '@theme/TabItem';
12+
13+
## Overview
14+
15+
A brief overview of the MCP server, its purpose, and key features. Link to the
16+
official documentation.
17+
18+
## Metadata
19+
20+
<MCPMetadata name='SERVER_NAME' />
21+
22+
## Usage
23+
24+
<Tabs groupId='mode' queryString='mode'>
25+
<TabItem value='ui' label='UI' default>
26+
27+
UI instructions go here. Only include a screenshot if it adds value, such as
28+
showing a unique configuration option or feature.
29+
30+
</TabItem>
31+
<TabItem value='cli' label='CLI'>
32+
33+
CLI instructions go here, with multiple usage examples specific to the MCP
34+
server.
35+
36+
```bash
37+
thv run ...
38+
```
39+
40+
If appropriate, include guidance for using network isolation and/or a custom
41+
permission profile.
42+
43+
</TabItem>
44+
<TabItem value='k8s' label='Kubernetes'>
45+
46+
Kubernetes manifest and instructions go here
47+
48+
```yaml title="SERVER_NAME.yaml"
49+
apiVersion: toolhive.stacklok.dev/v1alpha1
50+
kind: MCPServer
51+
```
52+
53+
</TabItem>
54+
</Tabs>
55+
56+
## Sample prompts
57+
58+
Provide sample prompts that users can use to interact with the MCP server.
59+
60+
## Recommended practices
61+
62+
- Include some recommended practices for using the MCP server safely and
63+
effectively

‎docs/toolhive/guides-mcp/context7.mdx‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: Context7 MCP server guide
3+
sidebar_label: Context7
4+
description:
5+
Using the Context7 MCP server with ToolHive for up-to-date documentation.
6+
last_update:
7+
author: danbarr
8+
date: 2025-08-27
9+
---
10+
11+
import Tabs from '@theme/Tabs';
12+
import TabItem from '@theme/TabItem';
13+
14+
## Overview
15+
16+
The [Context7 MCP server](https://github.com/upstash/context7) provides
17+
up-to-date, version-specific documentation and code examples straight from the
18+
source for any library or framework. Instead of relying on outdated training
19+
data, Context7 fetches current documentation and API references directly into
20+
your LLM's context, ensuring you get working code examples and accurate
21+
information.
22+
23+
Context7 eliminates common issues like hallucinated APIs that don't exist,
24+
outdated code patterns, and generic answers based on old package versions. It
25+
supports thousands of popular libraries including Next.js, React, MongoDB,
26+
Supabase, and many more.
27+
28+
Learn more at [context7.com](https://context7.com) and view the
29+
[project documentation](https://github.com/upstash/context7) for additional
30+
details.
31+
32+
## Metadata
33+
34+
<MCPMetadata name='context7' />
35+
36+
## Usage
37+
38+
While Context7 works without an API key, registering at
39+
[context7.com/dashboard](https://context7.com/dashboard) provides:
40+
41+
- Higher rate limits
42+
- Priority access during peak usage
43+
- Better performance for frequent queries
44+
45+
:::note
46+
47+
Currently, the Context7 MCP server only supports a CLI argument for the API key.
48+
This means ToolHive's secrets management cannot be used to inject the key.
49+
Instead, you must pass the API key directly as a command-line argument when
50+
starting the server.
51+
52+
:::
53+
54+
<Tabs groupId='mode' queryString='mode'>
55+
<TabItem value='ui' label='UI' default>
56+
57+
Select the `context7` MCP server in the ToolHive registry. The server works
58+
without authentication for basic usage, but you can add an API key for higher
59+
rate limits.
60+
61+
In the **Command arguments** section, optionally add `--api-key YOUR_API_KEY` if
62+
you have a Context7 API key. This provides higher rate limits and priority
63+
access.
64+
65+
:::tip[Security tip]
66+
67+
Enable outbound network filtering on the **Network Isolation** tab to restrict
68+
the server's network access using the default profile contained in the registry.
69+
70+
:::
71+
72+
</TabItem>
73+
<TabItem value='cli' label='CLI'>
74+
75+
Run with the default configuration (no API key required for basic usage):
76+
77+
```bash
78+
thv run context7
79+
```
80+
81+
If you have a Context7 API key for higher rate limits, pass it as an argument:
82+
83+
```bash
84+
thv run context7 -- --api-key <YOUR_API_KEY>
85+
```
86+
87+
Enable [network isolation](../guides-cli/network-isolation.mdx) using the
88+
default profile from the registry to restrict the server's network access:
89+
90+
```bash
91+
thv run --isolate-network context7
92+
```
93+
94+
Combine API key with network isolation:
95+
96+
```bash
97+
thv run --isolate-network context7 -- --api-key <YOUR_API_KEY>
98+
```
99+
100+
</TabItem>
101+
<TabItem value='k8s' label='Kubernetes'>
102+
103+
For basic usage without authentication:
104+
105+
```yaml title="context7.yaml"
106+
apiVersion: toolhive.stacklok.dev/v1alpha1
107+
kind: MCPServer
108+
metadata:
109+
name: context7
110+
namespace: toolhive-system
111+
spec:
112+
image: ghcr.io/stacklok/dockyard/npx/context7:1.0.14
113+
transport: stdio
114+
port: 8080
115+
permissionProfile:
116+
type: builtin
117+
name: network
118+
```
119+
120+
Apply the manifest to your cluster:
121+
122+
```bash
123+
kubectl apply -f context7.yaml
124+
```
125+
126+
For higher rate limits, add your API key as a command-line argument:
127+
128+
```yaml {8} title="context7-with-auth.yaml"
129+
apiVersion: toolhive.stacklok.dev/v1alpha1
130+
kind: MCPServer
131+
metadata:
132+
name: context7
133+
namespace: toolhive-system
134+
spec:
135+
image: ghcr.io/stacklok/dockyard/npx/context7:1.0.14
136+
args:
137+
- '--api-key'
138+
- 'YOUR_API_KEY'
139+
transport: stdio
140+
port: 8080
141+
permissionProfile:
142+
type: builtin
143+
name: network
144+
```
145+
146+
</TabItem>
147+
</Tabs>
148+
149+
## Sample prompts
150+
151+
Here are practical prompts you can use with the Context7 MCP server:
152+
153+
- "Create a Next.js middleware that checks for a valid JWT in cookies and
154+
redirects unauthenticated users to `/login`. Use context7"
155+
- "Show me how to set up MongoDB connection pooling with the latest MongoDB
156+
Node.js driver. Use context7"
157+
- "Configure a Supabase client with TypeScript types for a user authentication
158+
system. Use context7"
159+
- "Create a React component using the latest Tailwind CSS utility classes for a
160+
responsive navigation bar. Use context7"
161+
- "Show me how to implement server-side rendering with the current version of
162+
Nuxt.js. Use context7"
163+
- "Configure Redis caching with the Upstash Redis SDK for serverless functions.
164+
Use context7"
165+
166+
## Recommended practices
167+
168+
- Add `use context7` to your prompts to automatically fetch up-to-date
169+
documentation for the libraries you're working with.
170+
- When you know the exact library, you can specify it directly using the
171+
Context7 ID format: `use library /supabase/supabase for api and docs`
172+
- Consider setting up a rule in your MCP client to automatically invoke Context7
173+
for code-related queries, eliminating the need to manually add `use context7`
174+
to each prompt.
175+
- Use the `topic` parameter when requesting documentation to focus on specific
176+
areas like "routing", "authentication", or "deployment".
177+
- Register for an API key at
178+
[context7.com/dashboard](https://context7.com/dashboard) if you plan to make
179+
frequent requests or need higher rate limits.
180+
- Enable network isolation to restrict the server's outbound access.

‎docs/toolhive/guides-mcp/fetch.mdx‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: Fetch MCP server guide
3+
sidebar_label: Fetch
4+
description: Using the Fetch MCP server with ToolHive to retrieve website data.
5+
last_update:
6+
author: danbarr
7+
date: 2025-08-15
8+
---
9+
10+
import Tabs from '@theme/Tabs';
11+
import TabItem from '@theme/TabItem';
12+
13+
## Overview
14+
15+
A simple, lightweight MCP server that retrieves data from a website to add
16+
real-time context to an AI agent workflow.
17+
18+
[GoFetch](https://github.com/StacklokLabs/gofetch) is a Go implementation of the
19+
original
20+
[Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)
21+
with improved performance and security, built by Stacklok.
22+
23+
## Metadata
24+
25+
<MCPMetadata name='fetch' />
26+
27+
## Usage
28+
29+
<Tabs groupId='mode' queryString='mode'>
30+
<TabItem value='ui' label='UI' default>
31+
32+
Select the `fetch` MCP server in the ToolHive registry. No additional
33+
configuration is required to run it.
34+
35+
By default, it can access any website. To restrict its network access,
36+
[enable **network isolation**](../guides-ui/network-isolation.mdx) and enter the
37+
allowed hosts and ports.
38+
39+
</TabItem>
40+
<TabItem value='cli' label='CLI'>
41+
42+
Run with the default configuration:
43+
44+
```bash
45+
thv run fetch
46+
```
47+
48+
To control which website resources the server can access, create a custom
49+
permission profile:
50+
51+
```json title="fetch-profile.json"
52+
{
53+
"network": {
54+
"outbound": {
55+
"insecure_allow_all": false,
56+
"allow_host": [
57+
"host.docker.internal",
58+
"intranet.example.com",
59+
".googleapis.com"
60+
],
61+
"allow_port": [443]
62+
}
63+
}
64+
}
65+
```
66+
67+
Then run the server with the profile and
68+
[enable network isolation](../guides-cli/network-isolation.mdx):
69+
70+
```bash
71+
thv run --isolate-network --permission-profile fetch-profile.json fetch
72+
```
73+
74+
</TabItem>
75+
<TabItem value='k8s' label='Kubernetes'>
76+
77+
Create a Kubernetes manifest to deploy the Fetch MCP server:
78+
79+
```yaml title="fetch.yaml"
80+
apiVersion: toolhive.stacklok.dev/v1alpha1
81+
kind: MCPServer
82+
metadata:
83+
name: fetch
84+
namespace: toolhive-system
85+
spec:
86+
image: ghcr.io/stackloklabs/gofetch/server:0.0.5
87+
transport: streamable-http
88+
targetPort: 8080
89+
port: 8080
90+
permissionProfile:
91+
type: builtin
92+
name: network
93+
```
94+
95+
Apply the manifest to your Kubernetes cluster:
96+
97+
```bash
98+
kubectl apply -f fetch.yaml
99+
```
100+
101+
</TabItem>
102+
</Tabs>
103+
104+
## Sample prompts
105+
106+
Here are some sample prompts you can use to interact with the Fetch MCP server:
107+
108+
- "Fetch the latest news from `https://news.ycombinator.com`"
109+
- "Get the current weather for `https://weather.com`"
110+
- "Retrieve the latest blog posts from `https://example.com/blog`"
111+
112+
## Recommended practices
113+
114+
- Use network isolation to restrict the server's outbound network access to the
115+
specific hosts and ports required for your use case.
116+
- Enable [telemetry](../guides-cli/telemetry-and-metrics.md) to monitor tool
117+
usage including URL access for security and auditing purposes.

0 commit comments

Comments
 (0)