Run and connect to the server

This page shows you how to run a local agent and connect to a Data Commons MCP server running locally or remotely.

We provide specific instructions for the following agents:

  • Gemini CLI
    • Can be used for datacommons.org or a Custom Data Commons instance
    • Requires minimal setup

    See Use Gemini CLI for this option.

  • A sample basic agent based on the Google Agent Development Kit and Gemini Flash 2.5
    • Best for interacting with a Web UI
    • Can be used for datacommons.org or a Custom Data Commons instance
    • Can be customized to run other LLMs
    • Requires some additional setup

    See Use the sample agent for this option.

For an end-to-end tutorial using a server and agent over HTTP, see the sample Data Commons Colab notebook, Try Data Commons MCP Tools with a Custom Agent.

For other clients/agents, see the relevant documentation; you should be able to reuse the commands and arguments detailed below.

Prerequisites

Important: Additionally, for custom Data Commons instances: If you have not rebuilt your Data Commons image since the stable release of 2025-09-08, you must sync to the latest stable release, rebuild your image and redeploy.

Configure environment variables

Base Data Commons (datacommons.org)

For basic usage against datacommons.org, set the required DC_API_KEY in your shell/startup script (e.g. .bashrc).

export DC_API_KEY=YOUR API KEY

Custom Data Commons

If you’re running a against a custom Data Commons instance, we recommend using a .env file, which the server locates automatically, to keep all the settings in one place. All supported options are documented in https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/.env.sample.

To set variables using a .env file:

  1. From Github, download the file .env.sample to the desired directory. Or, if you plan to run the sample agent, clone the repo https://github.com/datacommonsorg/agent-toolkit/.

  2. From the directory where you saved the sample file, copy it to a new file called .env. For example: 
    cd ~/agent-toolkit/packages/datacommons-mcp
cp .env.sample .env
  3. Set the following variables:
    • DC_API_KEY: Set to your Data Commons API key
    • DC_TYPE: Set to custom.
    • CUSTOM_DC_URL: Uncomment and set to the URL of your instance.
  4. Optionally, set other variables.
  5. Save the file.

Use Gemini CLI

  1. Install Gemini CLI: see instructions at https://github.com/google-gemini/gemini-cli#quick-install.
  2. To configure Gemini CLI to recognize the Data Commons server, edit your ~/.gemini/settings.json file to add the following:
{
// ...
    "mcpServers": {
       "datacommons-mcp": {
           "command": "uvx",
            "args": [
                "datacommons-mcp@latest",
                "serve",
                "stdio"
            ],
            "env": {
                "DC_API_KEY": "YOUR DATA COMMONS API KEY"
            },
            "trust": true
        }
    }
// ...
}
  1. From any directory, run gemini.
  2. To see the Data Commons tools, use /mcp tools.
  3. Start sending natural-language queries.

Tip: To ensure that Gemini CLI uses the Data Commons MCP tools, and not its own GoogleSearch tool, include a prompt to use Data Commons in your query. For example, use a query like “Use Data Commons tools to answer the following: …” You can also add such a prompt to a GEMINI.md file so that it’s persisted across sessions.

Use the sample agent

We provide a basic agent for interacting with the MCP Server in packages/datacommons-mcp/examples/sample_agents/basic_agent. To run the agent locally:

  1. If not already installed, install uv for managing and installing Python packages; see the instructions at https://docs.astral.sh/uv/getting-started/installation/.
  2. From the desired directory, clone the agent-toolkit repo: 
    git clone https://github.com/datacommonsorg/agent-toolkit.git
  3. Set the following environment variables in your shell or startup script:
   export DC_API_KEY=YOUR DATA COMMONS API KEY
   export GEMINI_API_KEY=YOUR GOOGLE AI API KEY
  1. Go to the root directory of the repo: 
    cd agent-toolkit
  2. Run the agent using one of the following methods.
  1. Run the following command: 
    uvx --from google-adk adk web ./packages/datacommons-mcp/examples/sample_agents/
  2. Point your browser to the address and port displayed on the screen (e.g. http://127.0.0.1:8000/). The Agent Development Kit Dev UI is displayed.
  3. From the Type a message box, type your query for Data Commons or select another action.

Command line interface

  1. Run the following command: 
    uvx --from google-adk adk run ./packages/datacommons-mcp/examples/sample_agents/basic_agent
  2. Enter your queries at the User prompt in the terminal.

Sample queries

The Data Commons MCP tools excel at natural-language queries that involve:

  • Comparisons between two or more entities, such as countries or metrics
  • Exploring data available for a given topic

Here are some examples of such queries:

  • “What health data do you have for Africa?”
  • “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.”

Use a remote server/client

Run a standalone server

  1. Ensure you’ve set up the relevant server environment variables. If you’re using a .env file, go to the directory where the file is stored.
  2. Run: 
    uvx datacommons-mcp serve http [--port PORT]

    By default, the port is 8080 if you don’t set it explicitly.

The server is addressable with the endpoint mcp. For example, http://my-mcp-server:8080/mcp.

Connect to an already-running server from a remote client

Below we provide instructions for Gemini CLI and a sample ADK agent. If you’re using a different client, consult its documentation to determine how to specify an HTTP URL.

Gemini CLI

To configure Gemini CLI to connect to a remote Data Commons server over HTTP, replace the mcpServers section in ~/.gemini/settings.json (or other settings.json file) with the following:

{
// ... (additional configuration)
  "mcpServers": {
     "datacommons-mcp": {
       "httpUrl": "http://HOST:PORT/mcp"
      }
    // ... (other mcpServers entries)
   }
}

Sample agent

To configure the sample agent to connect to a remote Data Commons MCP server over HTTP, you need to modify the code in basic_agent/agent.py. Set import modules and agent initialization parameters as follows:

from google.adk.tools.mcp_tool.mcp_toolset import (
   MCPToolset,
   StreamableHTTPConnectionParams
)

root_agent = LlmAgent(
      # ...
      tools=[McpToolset(
         connection_params=StreamableHTTPConnectionParams(
            url=f"http://<host>:<port>/mcp"
         )
      )],
   )

Run the agent as described in Use the sample agent above.

Page last updated: October 24, 2025 • Send feedback about this page