Separate procedures for running a self-hosted MCP server to a new page

custom_dc/run_mcp_tools.md

@@ -1,14 +1,14 @@
 ---
 layout: default
-title: Run an MCP server
+title: Run MCP tools
 nav_order: 9
 parent: Build your own Data Commons
 ---
 
 {:.no_toc}
-# Run an MCP server
+# Run MCP tools
 
-To use Data Commons MCP tools with a Custom Data Commons, you must run your own instance of the Data Commons MCP server. This page describes how to run a server locally and in Google Cloud. 
+To use Data Commons MCP tools with a Custom Data Commons, you must run your own instance of the [Data Commons MCP server](https://pypi.org/project/datacommons-mcp/). This page describes how to run a server locally and in Google Cloud. 
 
 > **Important**: 
 > If you have not rebuilt your Data Commons image since the stable release of 2026-01-29, you must [sync to the latest stable release](/custom_dc/build_image.html#sync-code-to-the-stable-branch), [rebuild your image](/custom_dc/build_image.html#build-package) and [redeploy](/custom_dc/deploy_cloud.html#manage-your-service).
@@ -18,7 +18,7 @@ To use Data Commons MCP tools with a Custom Data Commons, you must run your own
 
 ## Run a local MCP server
 
-You can use any AI agent to spawn a local MCP server as a subprocess, or start a standalone server and connect to it from any client. For the most part, the procedures to do so are the same as those provided in [Run your own MCP server](/mcp/run_tools.html#self-hosted). The main difference is that you must set additional environment variables, as described below.
+You can use any AI agent to spawn a local MCP server as a subprocess, or start a standalone server and connect to it from any client. For the most part, the procedures to do so are the same as those provided in [Run your own MCP server](/mcp/host_server.html). The main difference is that you must set additional environment variables, as described below.
 
 ### Prerequisites
 
@@ -42,7 +42,7 @@ You can set variables in the following ways:
 
 ## Run the MCP Server in Google Cloud Platform
 
-If you have built a custom agent or Gemini CLI extension which you want to make publicly available, this page describes how to run the [Data Commons MCP server](https://pypi.org/project/datacommons-mcp/) in the cloud, using Google Cloud Run. 
+If you have built a custom agent or Gemini CLI extension which you want to make publicly available, the following sections describe how to run the MCP server in the cloud, using Google Cloud Run. 
 
 Since setting up an MCP server is a simple, one-time setup, there's no need to use Terraform to manage it. Data Commons provides a prebuilt Docker image in the Artifact Registry, so you only need to set up a new Cloud Run service to point to it. 
 
@@ -125,7 +125,7 @@ The following procedure sets up a bare-bones container service. To set additiona
 
 ### Connect to the server from a remote client
 
-For details, see [Configure an agent to connect to the running server](/mcp/run_tools.html#standalone-client).
+For details, see [Configure an agent to connect to the running server](/mcp/host_server.html#standalone-client).
 
 The HTTP URL parameter is the Cloud Run App URL, if you are exposing the service directly, or a custom domain URL if you are using a load balancer and domain mapping.
 
@@ -143,6 +143,3 @@ This is a generic message that could indicate a number of configuration problems
 - Be sure you have specified the `DC_API_KEY` environment variable.
 - Be sure you have specified the correct service account.
 - Try increasing the health check timeout.
-
-
-

mcp/host_server.md

@@ -0,0 +1,159 @@
+---
+layout: default
+title: Run an MCP Server
+nav_order: 3
+parent: MCP - Query data interactively with an AI agent
+---
+
+{:.no_toc}
+# Run a self-hosted MCP server
+
+This page describes how to run your own local Data Commons MCP server and connect to it from an agent. This is useful for advanced use cases, such as developing your own custom AI agent/client to use with Data Commons.
+
+For procedures for Custom Data Commons instances, please see instead [Run MCP tools](/custom_dc/run_mcp_tools.html).
+
+* TOC
+{:toc}
+
+We provide procedures for the following scenarios:
+- Local server and local agent: The agent spawns the server in a subprocess using Stdio as the transport protocol.
+- Remote server and local agent: You start up the server as a standalone process and then connect the agent to it using streaming HTTP as the protocol.
+
+For both scenarios, we use Gemini CLI and the sample agent as examples. You should be able to adapt the configurations to other MCP-compliant agents/clients.
+
+> **Tip:** For an end-to-end tutorial using a locally running server and agent over HTTP, see the sample Data Commons Colab notebook, [Try Data Commons MCP Tools with a Custom Agent](https://github.com/datacommonsorg/agent-toolkit/blob/main/notebooks/datacommons_mcp_tools_with_custom_agent.ipynb){: target="_blank"}.
+
+## Prerequisites
+
+In addition to a [Data Commons API key](run_tools.md#prerequisites), you will need the following:
+
+- Install `uv` for managing and installing Python packages; see the instructions at <https://docs.astral.sh/uv/getting-started/installation/>{: target="_blank"}. 
+
+## Run a local server and agent
+
+### Gemini CLI
+
+To instruct Gemini CLI to start up a local server using Stdio, replace the `datacommons-mcp` section in your `settings.json` file as follows:
+
+<pre>
+{
+   // ...
+   "mcpServers": {
+      "datacommons-mcp": {
+         "command": "uvx",
+         "args": [
+            "datacommons-mcp@latest",
+            "serve",
+            "stdio"
+         ],
+         // Only needed if you have not set the key in your environment
+         "env": "<var>YOUR DC API KEY</var>"
+      }
+   }
+   // ...
+}
+</pre>
+
+[Run Gemini CLI](run_tools.md#run-gemini) as usual.
+
+### Sample agent
+
+To instruct the sample agent to spawn a local server that uses the Stdio protocol, modify [`basic_agent/agent.py`](https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/examples/sample_agents/basic_agent/agent.py){: target="_blank"} to set import modules and agent initialization parameters as follows:
+
+```python
+from google.adk.tools.mcp_tool.mcp_toolset import (
+    McpToolset,
+    StdioConnectionParams,
+    StdioServerParameters,
+)
+
+#...
+
+root_agent = LlmAgent(
+    model=AGENT_MODEL,
+    name="basic_agent",
+    instruction=AGENT_INSTRUCTIONS,
+    tools=[
+        McpToolset(
+            connection_params=StdioConnectionParams(
+                timeout=10,
+                server_params=StdioServerParameters(
+                    command="uvx",
+                    args=["datacommons-mcp", "serve", "stdio"],
+                    env={"DC_API_KEY": DC_API_KEY}
+                )
+            )
+        )
+    ],
+)
+```
+[Run the startup commands](run_tools.md#run-sample) as usual.
+
+## Run a remote server and a local agent
+
+{: #standalone}
+### Step 1: Start the server as a standalone process
+
+1. Be sure to set the API key as an [environment variable](run_tools.md#prerequisites).
+2. Run:
+   <pre>
+   uvx datacommons-mcp serve http [--host <var>HOSTNAME</var>] [--port <var>PORT</var>]
+   </pre>
+   By default, the host is `localhost` and the port is `8080` if you don't set these flags explicitly.
+
+The server is addressable with the endpoint `mcp`. For example, `http://my-mcp-server:8080/mcp`.
+
+{: #standalone-client}
+### Step 2: Configure an agent to connect to the running server
+
+#### Gemini CLI
+
+Replace the `datacommons-mcp` section in your `settings.json` file as follows:
+<pre>
+{
+   "mcpServers": {
+      "datacommons-mcp": {
+         "httpUrl": "http://<var>HOST</var>:<var>PORT</var>/mcp",
+         "headers": {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream"
+            // If you have set the key in your environment
+           , "X-API-Key": "$DC_API_KEY"
+            // If you have not set the key in your environment
+           , "X-API-Key": "<var>YOUR DC API KEY</var>"
+         }
+      }
+   }
+}
+</pre>
+
+[Run Gemini CLI](run_tools.md#run-gemini) as usual.
+
+#### Sample agent
+
+Modify [`basic_agent/agent.py`](https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/examples/sample_agents/basic_agent/agent.py){: target="_blank"} as follows:
+
+<pre>
+from google.adk.tools.mcp_tool.mcp_toolset import (
+   MCPToolset,
+   StreamableHTTPConnectionParams
+)
+
+root_agent = LlmAgent(
+      # ...
+      tools=[McpToolset(
+         connection_params=StreamableHTTPConnectionParams(
+            url="http://<var>HOST</var>:<var>PORT</var>/mcp",
+            headers={
+               "Content-Type": "application/json",
+               "Accept": "application/json, text/event-stream"
+            }
+         )
+      )
+   ],
+)
+</pre>
+
+[Run the startup commands](run_tools.md#run-sample) as usual.
+
+<script src="/assets/js/customdc-doc-tabs.js"></script>

mcp/index.md

@@ -42,13 +42,13 @@ The server currently supports the following tools:
 
 ## Clients
 
-To connect to the Data Commons MCP Server, you can use any available AI application that supports MCP, or your own custom agent. 
+To connect to the Data Commons MCP Server, you can use any available AI application that supports MCP, or your own custom agent. See [Use MCP tools](run_tools.md) for procedures for using [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the [Gemini CLI Data Commons extension](https://geminicli.com/extensions/) with the hosted server.
 
 For self-hosted deployments, the server supports both standard MCP [transport protocols](https://modelcontextprotocol.io/docs/learn/architecture#transport-layer):
 - Streamable HTTP: For clients that connect remotely or otherwise require HTTP (e.g. Typescript)
 - Stdio: For clients that connect directly using local processes
 
-See [Run MCP tools](run_tools.md) for procedures for using [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the [Gemini CLI Data Commons extension](https://geminicli.com/extensions/).
+If you're interested in this option, see [Run a self-hosted MCP server](host_server.md) for procedures.
 
 ## Unsupported features