Getting started with the Inspector - UN System Data Commons MCP server

For first-time exploration, use the official MCP Inspector. It provides a graphical interface where you can see tools, resources, prompts, input schemas, tool responses and protocol activity — much easier than constructing MCP requests by hand.

1. Start the Inspector¶

From a terminal:

npx -y @modelcontextprotocol/inspector@2.6.0

Inspector 2.6.0 needs Node.js 22.19 or later. The Inspector prints a local URL similar to:

http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=...

Open the complete URL printed by the command, including the token.

2. Add the UN System Data Commons server¶

In the Inspector:

Open Servers and choose Add server.
Use a simple server ID, for example un-datacommons.
Select Streamable HTTP as the transport.

Enter the endpoint:

https://unsd-datacommons.gcp.un-icc.cloud/mcp

Do not add custom headers unless you have specifically been given authentication information — the server currently needs none.
Add and connect the server.

The server speaks MCP protocol version 2025-06-18. Newer clients negotiate down to it automatically; if the Inspector labels the connection as a “legacy” protocol era, that is why, and nothing is wrong.

A successful connection makes the server’s tools and resources visible in the Inspector. Open Resources first and read skill://data-commons-researcher/SKILL.md — the general research playbook — before running a search.

3. Check connectivity from the command line¶

You can confirm the endpoint is reachable, and discover what it exposes, without the graphical Inspector at all. Each recipe below was run against the live server when this page was written.

curl

Inspector CLI

Python

Claude Code

VS Code

The cleanest first check is the health endpoint next to the MCP path, which also tells you which server version is running:

URL='https://unsd-datacommons.gcp.un-icc.cloud/mcp'

curl -s "$URL/health"
# {"status":"OK","version":"1.3.0"}

A plain browser-style GET on the MCP path itself is not the method MCP uses, so it answers 405 — not an error with the service, just confirmation the endpoint is there:

curl -i "$URL"
# HTTP/2 405
# allow: POST, DELETE

A real MCP request is a JSON-RPC POST. The initialize handshake returns the server’s identity and capabilities (the answer arrives as a server-sent event, hence the data: prefix):

curl -s -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
# event: message
# data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18", ... "serverInfo":{"name":"DC MCP Server", ...

The same package has a non-interactive mode that speaks the protocol for you. --transport http is load-bearing: given a bare URL the CLI assumes the older SSE transport and the connection fails.

URL='https://unsd-datacommons.gcp.un-icc.cloud/mcp'

# the six tools
npx -y @modelcontextprotocol/inspector@2.6.0 --cli "$URL" \
  --transport http --method tools/list

# the skill resources
npx -y @modelcontextprotocol/inspector@2.6.0 --cli "$URL" \
  --transport http --method resources/list

# read the general research playbook
npx -y @modelcontextprotocol/inspector@2.6.0 --cli "$URL" \
  --transport http --method resources/read \
  --uri 'skill://data-commons-researcher/SKILL.md'

# prompts: currently {"prompts": []} — that is normal
npx -y @modelcontextprotocol/inspector@2.6.0 --cli "$URL" \
  --transport http --method prompts/list

No SDK is required for a first look — the transport is plain HTTP and JSON. This is the core of the client this book uses to check itself against the server on every build. It works because this server is stateless: it issues no Mcp-Session-Id. Against a stateful server you would have to echo that header on every call after initialize (the book’s own client does); without it such a server answers 400.

import json
import urllib.request

URL = "https://unsd-datacommons.gcp.un-icc.cloud/mcp"


def call(method, params=None, request_id=1):
    body = json.dumps(
        {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}}
    ).encode()
    request = urllib.request.Request(
        URL,
        data=body,
        method="POST",
        headers={
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
            "MCP-Protocol-Version": "2025-06-18",
        },
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        raw = response.read().decode()
    # Streamable HTTP may answer as JSON or as server-sent events.
    if raw.lstrip().startswith("{"):
        return json.loads(raw)["result"]
    data_lines = [line[5:] for line in raw.splitlines() if line.startswith("data:")]
    return json.loads(data_lines[-1])["result"]


server = call(
    "initialize",
    {
        "protocolVersion": "2025-06-18",
        "capabilities": {},
        "clientInfo": {"name": "probe", "version": "0"},
    },
)
print(server["serverInfo"])
print([tool["name"] for tool in call("tools/list", request_id=2)["tools"]])

claude mcp add --transport http --scope project un-datacommons \
  https://unsd-datacommons.gcp.un-icc.cloud/mcp

That writes .mcp.json at the repository root:

{
  "mcpServers": {
    "un-datacommons": {
      "type": "http",
      "url": "https://unsd-datacommons.gcp.un-icc.cloud/mcp"
    }
  }
}

Verify with claude mcp list (shows connection status), or /mcp inside a session, which lists the server, its tools and any failure details.

Create .vscode/mcp.json in your workspace (or run MCP: Add Server from the Command Palette and choose the HTTP type):

{
  "servers": {
    "un-datacommons": {
      "type": "http",
      "url": "https://unsd-datacommons.gcp.un-icc.cloud/mcp"
    }
  }
}

Start and inspect it from MCP: List Servers in the Command Palette, or from the MCP Servers – Installed section of the Extensions view.

Troubleshooting¶

“Connection lost” or “Error in input stream”: Make sure the local Inspector process is still running — the terminal in which you started it must remain active. If you pressed Ctrl-Z, the process is suspended but still holds its ports. Check with jobs -l and lsof -i :6274, bring it back with fg %1, stop it cleanly with Ctrl-C, then restart the Inspector.
Port 6274 is already in use: lsof -i :6274 shows which process owns it. If it is an old Inspector instance, stop that instance before starting another one.
The endpoint returns 405 to curl: Expected for a plain GET; see the curl tab above. Use the Inspector or an MCP-capable client to exercise the actual protocol.
401 or 403: Either your side of the network requires a proxy or credentials, or the endpoint has been placed behind authentication since this page was built. The server currently requires none; check GET …/mcp/health first — if that answers, the MCP path should too.
A tool answers with an error containing status 500: The MCP call itself worked; the server’s data backend refused the request. Two seen in the wild. unsupported SDMX component filter "donor" means a multi-entity request against data that has no entity dimensions — see Walkthrough C. failed to resolve place names: maps: REQUEST_DENIED means a place name the server could not match in its own index fell through to a geocoder that is not enabled: use the plain English short name (“Turkey”, “Iran”), not “Türkiye” or “Islamic Republic of Iran”. The search tools’ place parameters take names only; a DCID passed there fails the same way. DCIDs belong to the metadata and retrieval tools (entity_dcids, place_dcid, parent_place_dcid), which take the identifiers discovery returned.
Another UN Data Commons URL: Other addresses exist for other deployments (a Cloud Run run.app host, for example). They run different, older server versions with fewer tools and no playbooks, and they are not for external use. Everything in this book applies to https://unsd-datacommons.gcp.un-icc.cloud/mcp only.