From afdac7aef70e5b179b66422a8cfc521c3ce573e9 Mon Sep 17 00:00:00 2001 From: Kara Moscoe Date: Wed, 4 Feb 2026 10:07:30 -0800 Subject: [PATCH 1/2] Split self-hosted procedures into a separate page --- custom_dc/run_mcp_tools.md | 13 ++- mcp/host_server.md | 161 +++++++++++++++++++++++++++++++++++++ mcp/run_tools.md | 156 +---------------------------------- 3 files changed, 168 insertions(+), 162 deletions(-) create mode 100644 mcp/host_server.md diff --git a/custom_dc/run_mcp_tools.md b/custom_dc/run_mcp_tools.md index b6dde5bc4..fec3c5653 100644 --- a/custom_dc/run_mcp_tools.md +++ b/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. @@ -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. - - - diff --git a/mcp/host_server.md b/mcp/host_server.md new file mode 100644 index 000000000..aa0f0ea56 --- /dev/null +++ b/mcp/host_server.md @@ -0,0 +1,161 @@ +--- +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"}. + +**Additional prerequisities** + +- Install `uv` for managing and installing Python packages; see the instructions at {: 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: + +
+{
+   // ...
+   "mcpServers": {
+      "datacommons-mcp": {
+         "command": "uvx",
+         "args": [
+            "datacommons-mcp@latest",
+            "serve",
+            "stdio"
+         ],
+         // Only needed if you have not set the key in your environment
+         "env": "YOUR DC API KEY"
+      }
+   }
+   // ...
+}
+
+ +[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#sample) as usual. + +## Run a remote server and a local agent + +{:.no_toc} +{: #standalone} +### Step 1: Start the server as a standalone process + +1. Be sure to set the API key as an [environment variable](#prerequisites). +2. Run: + 
+   uvx datacommons-mcp serve http [--host HOSTNAME] [--port PORT]
+
+ 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} +{:.no_toc} +### Step 2: Configure an agent to connect to the running server + +{:.no_toc} +#### Gemini CLI + +Replace the `datacommons-mcp` section in your `settings.json` file as follows: +
+{
+   "mcpServers": {
+      "datacommons-mcp": {
+         "httpUrl": "http://HOST:PORT/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": "YOUR DC API KEY"
+         }
+      }
+   }
+}
+
+ +[Run Gemini CLI](run_tools.md#run-gemini) as usual. + +{:.no_toc} +#### 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: + +
+from google.adk.tools.mcp_tool.mcp_toolset import (
+   MCPToolset,
+   StreamableHTTPConnectionParams
+)
+
+root_agent = LlmAgent(
+      # ...
+      tools=[McpToolset(
+         connection_params=StreamableHTTPConnectionParams(
+            url=f"https://HOST:PORT/mcp",
+            headers={
+               "Content-Type": "application/json",
+               "Accept": "application/json, text/event-stream"
+            }
+         )
+      )
+   ],
+)
+
+ +[Run the startup commands](run_tools.md#run-sample) as usual. + + diff --git a/mcp/run_tools.md b/mcp/run_tools.md index 7399612ed..e2095bfc9 100644 --- a/mcp/run_tools.md +++ b/mcp/run_tools.md @@ -10,9 +10,9 @@ parent: MCP - Query data interactively with an AI agent This page describes how to run a local agent and connect to a Data Commons MCP server to query datacommons.org, using the centrally hosted server at `https://api.datacommons.org/mcp`. -For advanced use cases, this page also describes how to run your own local server and connect to it from an agent. +For advanced use cases, such as developing a custom agent, [Run a self-hosted MCP server](host_server.md) describes how to run your own local server and connect to it from an agent. -For procedures for Custom Data Commons instances, please see instead [Run an MCP server](/custom_dc/run_mcp_tools.html). +For procedures for Custom Data Commons instances, please see instead [Run MCP tools](/custom_dc/run_mcp_tools.html). * TOC {:toc} @@ -36,8 +36,6 @@ We provide specific instructions for the following agents. - Downloads agent code locally - Some additional setup -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"}. - For other clients/agents, see the relevant documentation; you should be able to easily adapt the configurations detailed here. ## Prerequisites @@ -258,153 +256,3 @@ Here are some examples of such queries: - "What data do you have on water quality in Zimbabwe?" - "Compare the life expectancy, economic inequality, and GDP growth for BRICS nations." - "Generate a concise report on income vs diabetes in US counties." - -{: #self-hosted} -## Advanced: Run your own MCP server - -This section describes how to run the Data Commons MCP server locally, and how to configure a client to connect to it. You can run the client locally or remotely. - -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. - -**Additional prerequisities** - -- Install `uv` for managing and installing Python packages; see the instructions at {: target="_blank"}. - -### Run a local server and agent - -{:.no_toc} -#### 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: - -
-{
-   // ...
-   "mcpServers": {
-      "datacommons-mcp": {
-         "command": "uvx",
-         "args": [
-            "datacommons-mcp@latest",
-            "serve",
-            "stdio"
-         ],
-         // Only needed if you have not set the key in your environment
-         "env": "YOUR DC API KEY"
-      }
-   }
-   // ...
-}
-
- -[Run Gemini CLI](#run-gemini) as usual. - -{:.no_toc} -#### 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-sample) as usual. - -### Run a remote server and a local agent - -{:.no_toc} -{: #standalone} -#### Step 1: Start the server as a standalone process - -1. Be sure to set the API key as an [environment variable](#prerequisites). -2. Run: - 
-   uvx datacommons-mcp serve http [--host HOSTNAME] [--port PORT]
-
- 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} -{:.no_toc} -#### Step 2: Configure an agent to connect to the running server - -{:.no_toc} -##### Gemini CLI - -Replace the `datacommons-mcp` section in your `settings.json` file as follows: -
-{
-   "mcpServers": {
-      "datacommons-mcp": {
-         "httpUrl": "http://HOST:PORT/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": "YOUR DC API KEY"
-         }
-      }
-   }
-}
-
- -[Run Gemini CLI](#run-gemini) as usual. - -{:.no_toc} -##### 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: - -
-from google.adk.tools.mcp_tool.mcp_toolset import (
-   MCPToolset,
-   StreamableHTTPConnectionParams
-)
-
-root_agent = LlmAgent(
-      # ...
-      tools=[McpToolset(
-         connection_params=StreamableHTTPConnectionParams(
-            url=f"https://HOST:PORT/mcp",
-            headers={
-               "Content-Type": "application/json",
-               "Accept": "application/json, text/event-stream"
-            }
-         )
-      )
-   ],
-)
-
- -[Run the startup commands](#run-sample) as usual. - - From a6b0791528d88c1b854e5b77c1a1601e708f6276 Mon Sep 17 00:00:00 2001 From: Kara Moscoe Date: Wed, 4 Feb 2026 10:25:57 -0800 Subject: [PATCH 2/2] various fixes --- mcp/host_server.md | 8 ++------ mcp/index.md | 2 +- mcp/run_tools.md | 2 +- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/mcp/host_server.md b/mcp/host_server.md index aa0f0ea56..5b30c155b 100644 --- a/mcp/host_server.md +++ b/mcp/host_server.md @@ -85,15 +85,14 @@ root_agent = LlmAgent( ], ) ``` -[Run the startup commands](run_tools.md#sample) as usual. +[Run the startup commands](run_tools.md#run-sample) as usual. ## Run a remote server and a local agent -{:.no_toc} {: #standalone} ### Step 1: Start the server as a standalone process -1. Be sure to set the API key as an [environment variable](#prerequisites). +1. Be sure to set the API key as an [environment variable](run_tools.md#prerequisites). 2. Run: 
    uvx datacommons-mcp serve http [--host HOSTNAME] [--port PORT]
@@ -103,10 +102,8 @@ root_agent = LlmAgent(
 The server is addressable with the endpoint `mcp`. For example, `http://my-mcp-server:8080/mcp`.
 
 {: #standalone-client}
-{:.no_toc}
 ### Step 2: Configure an agent to connect to the running server
 
-{:.no_toc}
 #### Gemini CLI
 
 Replace the `datacommons-mcp` section in your `settings.json` file as follows:
@@ -130,7 +127,6 @@ Replace the `datacommons-mcp` section in your `settings.json` file as follows:
 
 [Run Gemini CLI](run_tools.md#run-gemini) as usual.
 
-{:.no_toc}
 #### 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:
diff --git a/mcp/index.md b/mcp/index.md
index 30c78285d..2aa919015 100644
--- a/mcp/index.md
+++ b/mcp/index.md
@@ -48,7 +48,7 @@ For self-hosted deployments, the server supports both standard MCP [transport pr
 - 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/).
+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/).
 
 ## Unsupported features
 
diff --git a/mcp/run_tools.md b/mcp/run_tools.md
index e2095bfc9..b5f447113 100644
--- a/mcp/run_tools.md
+++ b/mcp/run_tools.md
@@ -89,7 +89,7 @@ gemini extensions install https://github.com/gemini-cli-extensions/datacommons [
 ```
 The installation creates a local `.gemini/extensions/datacommons` directory with the required files.
 
-> Note: If you have previously configured Gemini CLI to use the Data Commons MCP Server and want to use the extension instead, be sure to delete the `datacommons-mcp` section from the relevant `settings.json` file (e.g. `~/.gemini/settings.json`).
+> Note: If you have previously configured Gemini CLI to use Data Commons MCP tools and want to use the extension instead, be sure to delete the `datacommons-mcp` section from the relevant `settings.json` file (e.g. `~/.gemini/settings.json`).
 
 {:.no_toc}
 ### Run