datacommonsorg · kmoscoe · Feb 4, 2026 · Jun 12, 2025 · Jun 12, 2025 · Jun 12, 2025
diff --git a/api/index.md b/api/index.md
@@ -43,6 +43,7 @@ Finally, an R client library is available from a third-party provider, [Tidy Int
 A key is required for APIs to authenticate and authorize requests, as follows:
 - All REST [V2](rest/v2/index.md) APIs. These requests are served by endpoints at `api.datacommons.org`.
 - [Python and Pandas V2](python/v2/index.md) APIs, also served by `api.datacommons.org`.
+- Data Commons MCP server requests. These are served by `api.datacommons.org/mcp`. 
 - All requests coming from a custom Data Commons instance. These are also served by `api.datacommons.org`.
 - Data Commons NL API requests (used by the [DataGemma](https://ai.google.devgit/gemma/docs/datagemma){: target="_blank"} tool). These are served by endpoints at `nl.datacommons.org`.
 

diff --git a/assets/images/mcp.png b/assets/images/mcp.png
diff --git a/assets/images/mcp1.png b/assets/images/mcp1.png
diff --git a/assets/images/mcp2.png b/assets/images/mcp2.png
diff --git a/custom_dc/deploy_mcp_cloud.md → custom_dc/run_mcp_tools.md b/custom_dc/deploy_mcp_cloud.md → custom_dc/run_mcp_tools.md
@@ -1,22 +1,56 @@
 ---
 layout: default
-title: Run an MCP server in Google Cloud
+title: Run an MCP server
 nav_order: 9
 parent: Build your own Data Commons
 ---
 
 {:.no_toc}
-# Run an MCP server in Google Cloud
+# Run an MCP server
+
+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. 
+
+> **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).
+
+* TOC
+{:toc}
+
+## 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.
+
+### Prerequisites
+
+- Install `uv` for managing and installing Python packages; see the instructions at <https://docs.astral.sh/uv/getting-started/installation/>{: target="_blank"}. 
+
+### Configure environment variables
+
+To run against a Custom Data Commons instance, you must set the following required variables:
+- <code>DC_API_KEY="<var>YOUR API KEY</var>"</code>
+- `DC_TYPE="custom"`
+- <code>CUSTOM_DC_URL="<var>YOUR_INSTANCE_URL</var>"</code>
+
+Various other optional variables are also available; all are documented in [packages/datacommons-mcp/.env.sample](https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/.env.sample){: target="_blank"}. 
+
+You can set variables in the following ways:
+1. In a shell/startup script (e.g. `.bashrc`).
+1. Use an `.env` file. This is useful if you're setting multiple variables, to keep all settings in one place. Copy the contents of [`.env.sample`](https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/.env.sample){: target="_blank"} into a file called `.env` in the directory where you plan to run the server and/or agent.
+1. If you are using Gemini CLI (not the extension), you can use the `env` option in the `settings.json` file.
+
+<script src="/assets/js/customdc-doc-tabs.js"></script>
+
+## 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. 
 
 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. 
 
-## Prebuilt images
+### Prebuilt images
 
 There are several versions of the image available, viewable at <https://console.cloud.google.com/artifacts/docker/datcom-ci/us/gcr.io/datacommons-mcp-server>. We recommend that you choose a production version with a specific version number, to ensure that changes introduced by the Data Commons team don't break your application.
 
-## Before you start: decide on a hosting model
+### Before you start: decide on a hosting model
 
 There are several ways you can host the MCP server in Cloud Run, namely:
 
@@ -25,13 +59,13 @@ There are several ways you can host the MCP server in Cloud Run, namely:
 
 In this page, we provide steps for running the Data Commons MCP server as a standalone container. If you want to go with the sidecar option, please see [Deploying multiple containers to a service (sidecars)](https://docs.cloud.google.com/run/docs/deploying#sidecars){: target="_blank"} for additional requirements and setup procedures.
 
-## Prerequisites
+### Prerequisites
 
 The following procedures assume that you have set up the following Google Cloud Platform services, using the [Terraform scripts](deploy_cloud.md#terraform):
 - A service account and roles. 
 - A Google Cloud Secret Manager secret for storing your Data Commons API key. 
 
-## Create a Cloud Run Service for the MCP server
+### Create a Cloud Run Service for the MCP server
 
 The following procedure sets up a bare-bones container service. To set additional options, such as request timeouts, instance replication, etc., please see [Configure Cloud Run services](https://docs.cloud.google.com/run/docs/configuring){: target="_blank"} for details.
 
@@ -89,17 +123,16 @@ The following procedure sets up a bare-bones container service. To set additiona
 
 <script src="/assets/js/customdc-doc-tabs.js"></script>
 
-## Connect to the server from a remote client
+### Connect to the server from a remote client
 
-For details, see the following pages:
-- [Connect to the server from a local Gemini CLI client](/mcp/run_tools.html#gemini-cli-remote)
-- [Connect to the server from a local agent](/mcp/run_tools.html#remote)
+For details, see [Configure an agent to connect to the running server](/mcp/run_tools.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.
 
-## Troubleshoot deployment issues
+### Troubleshoot deployment issues
 
-### Container fails to start
+{:.no_toc}
+#### Container fails to start
 
 If you see this error message:
 

diff --git a/mcp/develop_agent.md b/mcp/develop_agent.md
diff --git a/mcp/index.md b/mcp/index.md
@@ -15,30 +15,38 @@ has_children: true
 
 The Data Commons [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) service gives AI agents access to the Data Commons knowledge graph and returns data related to statistical variables, topics, and observations. It allows end users to formulate complex natural-language queries interactively, get data in textual, structured or unstructured formats, and download the data as desired. For example, depending on the agent, a user can answer high-level questions such as "give me the economic indicators of the BRICS countries", view simple tables, and download a CSV file of the data in tabular format.
 
-The MCP server returns data from datacommons.org by default or can be configured to query a Custom Data Commons instance. 
+The MCP server returns data from datacommons.org ("base") by default. It can also be configured to query a Custom Data Commons instance. 
 
-The server is a Python binary based on the [FastMCP 2.0 framework](https://gofastmcp.com). A prebuilt package is available at <https://pypi.org/project/datacommons-mcp/>.
+For base Data Commons, the server is available as a hosted managed deployment to which you can connect from any AI agent running locally or remotely.
 
-At this time, there is no centrally deployed server; you run your own server, and any client you want to connect to it.
+![base Data Commons](/assets/images/mcp1.png)
 
-![alt text](/assets/images/mcp.png)
+You can also run your own MCP server locally, or in Google Cloud Platform. If you want to use the server to query a Custom Data Commons instance, you _must_ run your own. The server is available as:
+-  A prebuilt Python package for running locally
+-  A prebuilt Docker image for running in a Google Cloud Run service
 
-You can run the server and client locally, or you can run the server and client on different machines.
+![base or Custom Data Commons](/assets/images/mcp2.png)
 
 ## Tools
 
 The server currently supports the following tools:
 
-- `search_indicators`: Searches for available variables and/or topics (a hierarchy of sub-topics and member variables) for a given place or metric. 
-- `get_observations`: Fetches statistical data for a given variable and place.
+- `search_indicators`: Searches for available variables and/or topics (a hierarchy of sub-topics and member variables) for a given place or metric. This allows queries like:
+   - "Tell me what data you have about health in Egypt."
+   - "Do you have GDP data for Eastern European countries?"
+   - "What census data do you have for the U.S.?"
+- `get_observations`: Fetches statistical data for a given variable and place. This allows queries like:
+   - "List the population of Canada since 1964."
+   - "Rank-order the GDP for all countries in Eastern Europe."
+   - "Compare the life expectancy between different countries in South America."
 
 ## Clients
 
 To connect to the Data Commons MCP Server, you can use any available AI application that supports MCP, or your own custom agent. 
 
-The server supports both standard MCP [transport protocols](https://modelcontextprotocol.io/docs/learn/architecture#transport-layer):
-- Stdio: For clients that connect directly using local processes
+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/).