From e9f54955e1be43621380954f322e6da0e01301ba Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 7 Oct 2025 17:11:09 -0400 Subject: [PATCH 1/4] Add guide for notion-remote MCP server Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-mcp/notion-remote.mdx | 212 +++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 docs/toolhive/guides-mcp/notion-remote.mdx diff --git a/docs/toolhive/guides-mcp/notion-remote.mdx b/docs/toolhive/guides-mcp/notion-remote.mdx new file mode 100644 index 00000000..0f411187 --- /dev/null +++ b/docs/toolhive/guides-mcp/notion-remote.mdx @@ -0,0 +1,212 @@ +--- +title: Notion MCP server guide +sidebar_label: Notion +description: + Using the Notion remote MCP server with ToolHive to access your Notion + workspace. +last_update: + author: danbarr + date: 2025-10-07 +--- + +## Overview + +The official [Notion remote MCP server](https://developers.notion.com/docs/mcp) +provides access to your Notion workspace through the Notion API, allowing AI +agents to search, read, create, and manage pages, databases, and other content +in your Notion workspace. + +This is a remote MCP server that uses OAuth authentication with dynamic client +registration, meaning ToolHive handles all authentication setup automatically +with minimal configuration required. + +## Metadata + + + +## Usage + + + + +Select the `notion-remote` MCP server in the ToolHive registry. + +The server is preconfigured with the following settings: + +- **Server URL**: `https://mcp.notion.com/mcp` +- **Transport**: Streamable HTTP +- **Authorization method**: Dynamic Client Registration + +In the **Callback port** field, enter the port that ToolHive should use to +listen for the OAuth callback. This can be any available port on your machine. + +When you install the server, ToolHive: + +1. Discovers the OAuth endpoints automatically +2. Registers a new OAuth client with Notion +3. Opens your browser for authentication + +After you authorize access in your browser, the remote MCP server appears in +your server list with a "Running" status. + + + + +Run the Notion remote MCP server with the default configuration: + +```bash +thv run notion-remote +``` + +When you run the server, ToolHive: + +1. Discovers the OAuth endpoints automatically +2. Registers a new OAuth client with Notion +3. Opens your browser for authentication + +Customize the OAuth callback port if the default port (`8777`) is unavailable: + +```bash +thv run --remote-auth-callback-port 50051 notion-remote +``` + +After successful authentication, the server will be available to your configured +MCP clients. + +To restart the server (which triggers a new OAuth authentication flow): + +```bash +thv restart notion-remote +``` + + + + +:::note + +The ToolHive Kubernetes operator does not currently support remote MCP servers. +Instead, you can run the +[local Notion MCP server](https://github.com/makenotion/notion-mcp-server) in +Kubernetes using a static integration key. + +::: + +Create an integration in Notion to obtain an authentication token by following +the instructions in the MCP server's +[README](https://github.com/makenotion/notion-mcp-server?tab=readme-ov-file#installation). + +Create a Kubernetes secret containing your Notion integration token +("`ntn_****`"): + +```bash +kubectl -n toolhive-system create secret generic notion-token --from-literal=token= +``` + +Create a Kubernetes manifest to deploy the Notion MCP server using your secret: + +```yaml {14-17} title="notion.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: notion + namespace: toolhive-system +spec: + image: ghcr.io/stacklok/dockyard/npx/notion:1.9.0 + transport: stdio + port: 8080 + permissionProfile: + type: builtin + name: network + secrets: + - name: notion-token + key: token + targetEnvName: NOTION_TOKEN +``` + +Apply the manifest to your Kubernetes cluster: + +```bash +kubectl apply -f notion.yaml +``` + + + + +## Sample prompts + +Here are some sample prompts you can use to interact with the Notion MCP server: + +- "Search my Notion workspace for pages about 'project planning'" +- "Create a new page in my Notion workspace titled 'Meeting Notes' with today's + date" +- "Find all database entries in my Task List database where status is 'To Do'" +- "Update the page titled 'Weekly Report' with a summary of this week's + accomplishments" +- "List all pages in my 'Engineering' teamspace" +- "Create a new Notion database for tracking customer feedback with columns for + name, date, and feedback text" +- "Add a comment to the page titled 'Q4 Planning' with my feedback" +- "Search for pages created by john@example.com in the last 30 days" + +## Recommended practices + +- **Scope your access**: When authenticating, review the permissions requested + and only grant access to the workspaces you need for your use case. +- **Test with read operations**: Start with search and fetch operations to + familiarize yourself with the server's capabilities before making changes to + your workspace. +- **Use specific searches**: Instead of broad workspace searches, narrow down + results by searching within specific pages, databases, or teamspaces for + better performance. +- **Understand the data model**: Notion has a specific hierarchy (workspaces, + teamspaces, pages, databases, data sources). Understanding this structure + helps craft more effective prompts. +- **Be cautious with updates**: The MCP server can modify and delete content in + your Notion workspace. Always review changes before applying them to important + pages or databases. +- **Handle authentication errors**: If you see authentication errors, restart + the server to trigger a new OAuth flow: `thv restart notion-remote` + +## Troubleshooting + +
+OAuth authentication fails + +If OAuth authentication fails or times out: + +1. Ensure the callback port is not blocked by a firewall +2. Check that your browser allows pop-ups from ToolHive +3. Try restarting the server with `thv restart notion-remote` + +
+
+Server shows "Running" but tools don't work + +The server may have lost authentication. Restart the server to re-authenticate: + +```bash +thv restart notion-remote +``` + +
+
+Can't find content in search results + +- Notion search uses semantic search, which may return different results than + exact keyword matching +- Try using more specific search terms or filtering by page, database, or + teamspace +- Check that you have access to the content you're searching for (permissions + may limit results) + +
+
+Rate limits + +Notion's API has rate limits. If you encounter rate limit errors: + +- Reduce the frequency of requests +- Use more specific queries to reduce the amount of data retrieved +- Wait for the rate limit to reset (typically a few minutes) + +
From 2334c5cd6649952faf7c5e925faddd346c9281d9 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 7 Oct 2025 17:31:38 -0400 Subject: [PATCH 2/4] Refresh Context7 guide - Add remote server option - Update to use new env var for API key Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-mcp/context7.mdx | 85 ++++++++++++++------------- 1 file changed, 45 insertions(+), 40 deletions(-) diff --git a/docs/toolhive/guides-mcp/context7.mdx b/docs/toolhive/guides-mcp/context7.mdx index 77870c5b..75f131cd 100644 --- a/docs/toolhive/guides-mcp/context7.mdx +++ b/docs/toolhive/guides-mcp/context7.mdx @@ -5,7 +5,7 @@ description: Using the Context7 MCP server with ToolHive for up-to-date documentation. last_update: author: danbarr - date: 2025-08-27 + date: 2025-10-08 --- ## Overview @@ -39,25 +39,21 @@ While Context7 works without an API key, registering at - Priority access during peak usage - Better performance for frequent queries -:::note + + -Currently, the Context7 MCP server only supports a CLI argument for the API key. -This means ToolHive's secrets management cannot be used to inject the key as an -environment variable. Instead, you must pass the API key directly as a -command-line argument when starting the server. +**Remote MCP server** -::: +Select the `context7-remote` MCP server in the ToolHive registry. Currently, +ToolHive doesn't support adding custom headers for remote MCP servers, so using +the remote server is limited to basic usage without an API key. - - +**Local MCP server** -Select the `context7` MCP server in the ToolHive registry. The server works -without authentication for basic usage, but you can add an API key for higher -rate limits. +Select the `context7` MCP server in the ToolHive registry. -In the **Command arguments** section, optionally add `--api-key YOUR_API_KEY` if -you have a Context7 API key. This provides higher rate limits and priority -access. +The server works without authentication for basic usage, but you can optionally +add an API key in the **Secrets** section for higher rate limits. :::tip[Security tip] @@ -69,19 +65,18 @@ the server's network access using the default profile contained in the registry. -Run with the default configuration (no API key required for basic usage): +For basic (unauthenticated) usage, you can connect directly to Context7's public +MCP server: ```bash -thv run context7 +thv run context7-remote ``` -If you have a Context7 API key for higher rate limits, you can pass it directly -as a command-line argument. You can store the key in a ToolHive secret and -retrieve it when starting the server: +Alternatively, run the local containerized MCP server with the default +configuration (no API key required for basic usage): ```bash -thv secret set context7 -thv run context7 -- --api-key $(thv secret get context7) +thv run context7 ``` Enable [network isolation](../guides-cli/network-isolation.mdx) using the @@ -91,10 +86,18 @@ default profile from the registry to restrict the server's network access: thv run --isolate-network context7 ``` +If you have a Context7 API key for higher rate limits, create a secret named +`context7` containing your API key and run the server with the `--secret` flag: + +```bash +thv secret set context7 +thv run --secret context7,target=CONTEXT7_API_KEY context7 +``` + Combine API key with network isolation: ```bash -thv run --isolate-network context7 -- --api-key $(thv secret get context7) +thv run --secret context7,target=CONTEXT7_API_KEY --isolate-network context7 ``` @@ -109,7 +112,7 @@ metadata: name: context7 namespace: toolhive-system spec: - image: ghcr.io/stacklok/dockyard/npx/context7:1.0.14 + image: ghcr.io/stacklok/dockyard/npx/context7:1.0.21 transport: stdio port: 8080 ``` @@ -120,21 +123,23 @@ Apply the manifest to your cluster: kubectl apply -f context7.yaml ``` -For higher rate limits, add your API key as a command-line argument: +If you have a Context7 API key for higher rate limits, create a Kubernetes +secret containing your Context7 API key: -```yaml {8} title="context7-with-auth.yaml" -apiVersion: toolhive.stacklok.dev/v1alpha1 -kind: MCPServer -metadata: - name: context7 - namespace: toolhive-system +```bash +kubectl -n toolhive-system create secret generic context7-api-key --from-literal=token= +``` + +Then add a `secrets` section to the manifest file above to pass the API key as +an environment variable: + +```yaml title="context7-with-auth.yaml" spec: - image: ghcr.io/stacklok/dockyard/npx/context7:1.0.14 - args: - - '--api-key' - - 'YOUR_API_KEY' - transport: stdio - port: 8080 + # ... + secrets: + - name: context7-api-key + key: token + targetEnvName: CONTEXT7_API_KEY ``` @@ -159,10 +164,10 @@ Here are practical prompts you can use with the Context7 MCP server: ## Recommended practices -- Add `use context7` to your prompts to automatically fetch up-to-date +- Include `use context7` in your prompts to automatically fetch current documentation for the libraries you're working with. -- When you know the exact library, you can specify it directly using the - Context7 ID format: `use library /supabase/supabase for api and docs` +- When you know the exact library, specify it directly using the Context7 ID + format, for example: `use library /supabase/supabase for api and docs` - Consider setting up a rule in your MCP client to automatically invoke Context7 for code-related queries, eliminating the need to manually add `use context7` to each prompt. From ec1e88b048b19a00dd009313be5ee561a45f6a22 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 7 Oct 2025 17:32:05 -0400 Subject: [PATCH 3/4] Bump pinned versions in MCP examples Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-mcp/fetch.mdx | 4 +-- docs/toolhive/guides-mcp/github.mdx | 4 +-- docs/toolhive/guides-mcp/k8s.mdx | 4 +-- docs/toolhive/guides-mcp/playwright.mdx | 35 +++++++++++++++---------- 4 files changed, 27 insertions(+), 20 deletions(-) diff --git a/docs/toolhive/guides-mcp/fetch.mdx b/docs/toolhive/guides-mcp/fetch.mdx index 1f7d16c5..c8c9367d 100644 --- a/docs/toolhive/guides-mcp/fetch.mdx +++ b/docs/toolhive/guides-mcp/fetch.mdx @@ -4,7 +4,7 @@ sidebar_label: Fetch description: Using the Fetch MCP server with ToolHive to retrieve website data. last_update: author: danbarr - date: 2025-08-15 + date: 2025-10-07 --- ## Overview @@ -80,7 +80,7 @@ metadata: name: fetch namespace: toolhive-system spec: - image: ghcr.io/stackloklabs/gofetch/server:0.0.5 + image: ghcr.io/stackloklabs/gofetch/server:1.0.1 transport: streamable-http targetPort: 8080 port: 8080 diff --git a/docs/toolhive/guides-mcp/github.mdx b/docs/toolhive/guides-mcp/github.mdx index 6267fabf..8a6f0948 100644 --- a/docs/toolhive/guides-mcp/github.mdx +++ b/docs/toolhive/guides-mcp/github.mdx @@ -5,7 +5,7 @@ description: Using the GitHub MCP server with ToolHive for repository management. last_update: author: danbarr - date: 2025-08-15 + date: 2025-10-07 --- ## Overview @@ -141,7 +141,7 @@ metadata: name: github namespace: toolhive-system spec: - image: ghcr.io/github/github-mcp-server:v0.13.0 + image: ghcr.io/github/github-mcp-server:v0.17.1 transport: stdio port: 8080 secrets: diff --git a/docs/toolhive/guides-mcp/k8s.mdx b/docs/toolhive/guides-mcp/k8s.mdx index e3e76b0b..42d652ac 100644 --- a/docs/toolhive/guides-mcp/k8s.mdx +++ b/docs/toolhive/guides-mcp/k8s.mdx @@ -5,7 +5,7 @@ description: Using the Kubernetes (MKP) MCP server with ToolHive for cluster management. last_update: author: danbarr - date: 2025-09-02 + date: 2025-10-07 --- ## Overview @@ -132,7 +132,7 @@ metadata: name: mkp namespace: toolhive-system spec: - image: ghcr.io/stackloklabs/mkp/server:0.2.1 + image: ghcr.io/stackloklabs/mkp/server:0.2.4 transport: streamable-http targetPort: 8080 port: 8080 diff --git a/docs/toolhive/guides-mcp/playwright.mdx b/docs/toolhive/guides-mcp/playwright.mdx index 3a615b97..d53af040 100644 --- a/docs/toolhive/guides-mcp/playwright.mdx +++ b/docs/toolhive/guides-mcp/playwright.mdx @@ -5,7 +5,7 @@ description: Using the Playwright MCP server with ToolHive for browser automation. last_update: author: danbarr - date: 2025-08-27 + date: 2025-10-07 --- import useBaseUrl from '@docusaurus/useBaseUrl'; @@ -105,13 +105,13 @@ thv run playwright Emulate a mobile device for responsive testing: ```bash -thv run playwright -- --port 8931 --device "iPhone 15" +thv run playwright -- --port 8931 --allowed-hosts "*" --device "iPhone 15" ``` Restrict access to specific domains: ```bash -thv run playwright -- --port 8931 --allowed-origins "example.com;trusted-site.com" +thv run playwright -- --port 8931 --allowed-hosts "*" --allowed-origins "example.com;trusted-site.com" ``` Mount a host directory (e.g., `~/playwright-output`) to save browser output @@ -119,21 +119,21 @@ files like screenshots and traces: ```bash mkdir ~/playwright-output -thv run --volume ~/playwright-output:/browser-output playwright -- --port 8931 --output-dir /browser-output --save-trace --save-session +thv run --volume ~/playwright-output:/browser-output playwright -- --port 8931 --allowed-hosts "*" --output-dir /browser-output --save-trace --save-session ``` You can run multiple instances of the server with different configurations by giving each a unique name: ```bash -thv run --name playwright-desktop playwright -- --port 8931 --device "Desktop Chrome" --viewport-size 1920,1080 -thv run --name playwright-iphone playwright -- --port 8931 --device "iPhone 15" +thv run --name playwright-desktop playwright -- --port 8931 --allowed-hosts "*" --device "Desktop Chrome" --viewport-size 1920,1080 +thv run --name playwright-iphone playwright -- --port 8931 --allowed-hosts "*" --device "iPhone 15" ``` :::note[Important] -Don't remove the `--port 8931` argument, as the server requires it to function -correctly in ToolHive. +Don't remove the `--port 8931` or ` --allowed-hosts "*"` arguments, as the +server requires it to function correctly in ToolHive. ::: @@ -149,13 +149,15 @@ metadata: name: playwright namespace: toolhive-system spec: - image: mcr.microsoft.com/playwright/mcp:v0.0.36 + image: mcr.microsoft.com/playwright/mcp:v0.0.41 transport: streamable-http targetPort: 8931 port: 8080 args: - '--port' - '8931' + - '--allowed-hosts' + - '*' ``` Apply the manifest to your Kubernetes cluster: @@ -164,22 +166,25 @@ Apply the manifest to your Kubernetes cluster: kubectl apply -f playwright.yaml ``` -For production deployments with network restrictions: +For production deployments with network restrictions, add the +`--allowed-origins` argument with a list of trusted domains: -```yaml title="playwright-restricted.yaml" +```yaml {16-17} title="playwright-restricted.yaml" apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: name: playwright namespace: toolhive-system spec: - image: mcr.microsoft.com/playwright/mcp:v0.0.36 + image: mcr.microsoft.com/playwright/mcp:v0.0.41 transport: streamable-http targetPort: 8931 port: 8080 args: - '--port' - '8931' + - '--allowed-hosts' + - '*' - '--allowed-origins' - 'example.com;trusted-domain.org' ``` @@ -187,20 +192,22 @@ spec: Mount a persistent volume to save browser output files like screenshots and traces: -```yaml {13-14,22-25,28-31} title="playwright-with-volume.yaml" +```yaml {16-17,25-28,31-34} title="playwright-with-volume.yaml" apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: name: playwright namespace: toolhive-system spec: - image: mcr.microsoft.com/playwright/mcp:v0.0.36 + image: mcr.microsoft.com/playwright/mcp:v0.0.41 transport: streamable-http targetPort: 8931 port: 8080 args: - '--port' - '8931' + - '--allowed-hosts' + - '*' - '--output-dir' - '/browser-output' - '--save-trace' From 8e75d8e13353d07652d1e65692486e0d5bf861f2 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 7 Oct 2025 17:40:25 -0400 Subject: [PATCH 4/4] Reformat the long playwright CLI lines Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-mcp/playwright.mdx | 49 +++++++++++++++++-------- 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/docs/toolhive/guides-mcp/playwright.mdx b/docs/toolhive/guides-mcp/playwright.mdx index d53af040..1ff95a11 100644 --- a/docs/toolhive/guides-mcp/playwright.mdx +++ b/docs/toolhive/guides-mcp/playwright.mdx @@ -78,18 +78,18 @@ in the **Storage volumes** section and add the `--output-dir ` command argument as shown in the screenshot below. :::note[Important] -Don't remove the `--port 8931` argument, as the server requires it to function -correctly in ToolHive. +Don't remove the `--port 8931` or `--allowed-hosts "*"` arguments. They are +required for the server to function correctly in ToolHive. ::: @@ -104,36 +104,46 @@ thv run playwright Emulate a mobile device for responsive testing: -```bash -thv run playwright -- --port 8931 --allowed-hosts "*" --device "iPhone 15" +```bash {2} +thv run playwright -- --port 8931 --allowed-hosts "*" \ + --device "iPhone 15" ``` Restrict access to specific domains: -```bash -thv run playwright -- --port 8931 --allowed-hosts "*" --allowed-origins "example.com;trusted-site.com" +```bash {2} +thv run playwright -- --port 8931 --allowed-hosts "*" \ + --allowed-origins "example.com;trusted-site.com" ``` Mount a host directory (e.g., `~/playwright-output`) to save browser output files like screenshots and traces: -```bash +```bash {3,5} mkdir ~/playwright-output -thv run --volume ~/playwright-output:/browser-output playwright -- --port 8931 --allowed-hosts "*" --output-dir /browser-output --save-trace --save-session +thv run \ + --volume ~/playwright-output:/browser-output playwright \ + -- --port 8931 --allowed-hosts "*" \ + --output-dir /browser-output --save-trace --save-session ``` You can run multiple instances of the server with different configurations by giving each a unique name: -```bash -thv run --name playwright-desktop playwright -- --port 8931 --allowed-hosts "*" --device "Desktop Chrome" --viewport-size 1920,1080 -thv run --name playwright-iphone playwright -- --port 8931 --allowed-hosts "*" --device "iPhone 15" +```bash {1,5} +thv run --name playwright-desktop playwright \ + -- --port 8931 --allowed-hosts "*" \ + --device "Desktop Chrome" --viewport-size 1920,1080 + +thv run --name playwright-iphone playwright \ + -- --port 8931 --allowed-hosts "*" \ + --device "iPhone 15" ``` :::note[Important] -Don't remove the `--port 8931` or ` --allowed-hosts "*"` arguments, as the -server requires it to function correctly in ToolHive. +Don't remove the `--port 8931` or `--allowed-hosts "*"` arguments. They are +required for the server to function correctly in ToolHive. ::: @@ -160,6 +170,13 @@ spec: - '*' ``` +:::note[Important] + +Don't remove the `--port 8931` or `--allowed-hosts "*"` arguments. They are +required for the server to function correctly in ToolHive. + +::: + Apply the manifest to your Kubernetes cluster: ```bash @@ -234,7 +251,7 @@ spec: Here are some sample prompts you can use to interact with the Playwright MCP server: -- "Navigate to https://example.com and take a screenshot of the homepage" +- "Navigate to https://toolhive.dev and take a screenshot of the homepage" - "Go to the login page, fill in the username field with 'testuser' and password field with 'password123', then click the login button" - "Open https://news.ycombinator.com and get the titles of the top 5 stories"