/mcp",
- headers={
- "Content-Type": "application/json",
- "Accept": "application/json, text/event-stream"
- },
- ),
- )
- ],
-)
-```
+{:.no_toc}
+#### 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](https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/examples/sample_agents/basic_agent/instructions.py){: target="_blank"}.
+
+You can add your own prompts to modify how the agent handles tool results. See the Google ADK page on [LLM agent instructions](https://google.github.io/adk-docs/agents/llm-agents/#guiding-the-agent-instructions-instruction){: target="_blank"} for tips on how to write good prompts.
## Sample queries
@@ -340,19 +259,152 @@ Here are some examples of such queries:
- "Compare the life expectancy, economic inequality, and GDP growth for BRICS nations."
- "Generate a concise report on income vs diabetes in US counties."
-## Run a standalone server
+{: #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
-The following procedure starts the MCP server in a local environment. To run the server in Google Cloud against a Custom Data Commons instance, see [Run an MCP server in Google Cloud](/custom_dc/deploy_mcp_cloud.html)
+To instruct Gemini CLI to start up a local server using Stdio, replace the `datacommons-mcp` section in your `settings.json` file as follows:
-1. Ensure you've set up the relevant server [environment variables](#configure-environment-variables). If you're using a `.env` file, go to the directory where the file is stored.
-1. Run:
+
+{
+ // ...
+ "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.
+ 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`.
-You can connect to the server using [Gemini CLI](#use-gemini-cli) or the [sample ADK agent](#use-the-sample-agent). If you're using a different client from the ones documented on this page, consult its documentation to determine how to specify an HTTP URL.
+{: #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.