Use MCP tools

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, such as developing a custom agent, Run a self-hosted MCP server 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 MCP tools.

Prerequisites
- Configure environment variable
Use the Gemini CLI extension
Use Gemini CLI
Use the sample agent
Sample queries

We provide specific instructions for the following agents.

Gemini CLI extension
- Best for querying datacommons.org
- Provides a built-in “agent” and context file for Data Commons
- Downloads extension files locally
- Minimal setup
Gemini CLI
- No additional downloads
- You can create your own LLM context file
- Minimal setup
A sample basic agent based on the Google Agent Development Kit
- Best for interacting with a Web GUI
- Can be used to run other LLMs and prompts
- Downloads agent code locally
- Some additional setup

For other clients/agents, see the relevant documentation; you should be able to easily adapt the configurations detailed here.

Prerequisites

This is required for all agents, regardless of the server deployment:

A (free) Data Commons API key. To obtain an API key, go to https://apikeys.datacommons.org and request a key for the api.datacommons.org domain.

Other requirements for specific agents are given in their respective sections.

Configure environment variable

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

Linux or Mac shell
Windows Powershell

   export DC_API_KEY="YOUR API KEY"

   $env:DC_API_KEY="YOUR API KEY"

Tip: If you are using Gemini CLI (not the extension), you can skip this step and specify the key in the Gemini CLI configuration file.

Use the Gemini CLI extension

Additional prerequisites

In addition to the Data Commons API key, you must install the following:

When you install the extension, it clones the Data Commons extension Github repo to your local system.

Install

Open a new terminal and install the extension directly from GitHub:

gemini extensions install https://github.com/gemini-cli-extensions/datacommons [--auto-update]

The installation creates a local .gemini/extensions/datacommons directory with the required files.

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).

Run

Run gemini from any directory.
To verify that the Data commons tools are running, enter /mcp list. You should see datacommons-mcp listed as Ready. If you don’t, see the Troubleshoot section.
To verify that the extension is running, enter /extensions list. You should see datacommons listed as active.
Start sending natural-language queries.

Update

After starting up Gemini CLI, you may see the message You have one extension with an update available.

In this case, run /extensions list. If datacommons is displayed with update available, enter the following in the Gemini input field:

/extensions update datacommons

Troubleshoot

You can diagnose common errors, such as invalid API keys, by using the debug flag:

gemini -d

You can also use the Ctrl-o option from inside the Gemini input field.

Here are solutions to some commonly experienced problems.

Install/update/uninstall hangs and does not complete

Check that you are not running the gemini extensions command from inside the Gemini input field. Start a new terminal and run it from the command line.
Check that you’ve spelled commands correctly, e.g. extensions and not extension.

datacommons-mcp is disconnected

This is usually due to a missing Data Commons API key. Be sure to obtain a key and export it on the command line or in a startup script (e.g. .bashrc). If you’ve exported it in a startup script, be sure to start a new terminal.

Failed to clone Git repository

Make sure you have installed Git on your system.

Uninstall

To uninstall the extension, run:

gemini extensions uninstall datacommons

Use Gemini CLI

In addition to the Data Commons API key, you must install the following:

Google Gemini CLI

Configure

To configure Gemini CLI to connect to the Data Commons server, edit the relevant settings.json file (e.g. ~/.gemini/settings.json) to add the following:

{
   ...
   "mcpServers": {
     "datacommons-mcp": {
         "httpUrl": "https://api.datacommons.org/mcp",
         "headers": {
           // 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

From any directory, run gemini.
To see the Data Commons tools, use /mcp tools.
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

Additional prerequisites

In addition to the Data Commons API key, you will need:

Git installed.
uv, a Python package manager, installed.

Tip: You do not need to install the Google ADK; when you use the command we provide to start the agent, it downloads the ADK dependencies at run time.

Install

From the desired directory, clone the agent-toolkit repo:

git clone https://github.com/datacommonsorg/agent-toolkit.git

Run

Go to the root directory of the repo:
```
cd agent-toolkit
```
Run the agent using one of the following methods.

Web UI (recommended)

Run the following command:

uvx --from google-adk adk web ./packages/datacommons-mcp/examples/sample_agents/

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.
From the Type a message box, type your query for Data Commons or select another action.

Command line interface

Run the following command:

uvx --from google-adk adk run ./packages/datacommons-mcp/examples/sample_agents/basic_agent

Enter your queries at the User prompt in the terminal.

Customize the agent

To customize the sample agent, you can make changes directly to the Python files. You’ll need to restart the agent any time you make changes.

Customize the model

To change to a different LLM or model version, edit the AGENT_MODEL constant in packages/datacommons-mcp/examples/sample_agents/basic_agent/agent.py.

Customize agent behavior

The agent’s behavior is determined by prompts provided in the AGENT_INSTRUCTIONS in packages/datacommons-mcp/examples/sample_agents/basic_agent/instructions.py.

You can add your own prompts to modify how the agent handles tool results. See the Google ADK page on LLM agent instructions for tips on how to write good prompts.

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.”

Page last updated: February 13, 2026 • Send feedback about this page