MCP Setup & Usage Guide

Overview

The Dewey Data MCP server is a Model Context Protocol (MCP) integration that connects AI coding assistants and agents directly to the Dewey Data platform. Once configured, your AI assistant can search datasets, explore schemas, preview sample data, and retrieve download details — all without leaving your development environment.

This guide covers installation for:

Claude Code
OpenAI Codex
Gemini CLI

Prerequisites

Before installing, make sure you have:

A Dewey account with an active subscription — deweydata.io
A Dewey API key — Generate one by going to:

deweydata.io → Connections → Add Connection → API Key

⚠️
Save your API key immediately. It is only shown once at creation time.
Your Dewey MCP server URL — https://api.deweydata.io/mcp

Installation

Claude Code

Open up the Claude application, select the Claude Code tab, and copy and paste the following into the prompt. Make sure you replace the {YOUR_API_KEY_HERE} with your api key.

Add "dewey-prod" as an available MCP to my .claude.json config file in "mcpServers". If "mcpServers" does not already exist, add it. In "headers", add my "X-API-KEY": "{YOUR_API_KEY_HERE}".
"mcpServers": {
    "dewey-prod": {
      "type": "http",
      "url": "https://api.deweydata.io/mcp",
      "headers": {
        "X-API-KEY": "{YOUR_API_KEY_HERE}"
      }
    }
  }

Follow the instructions until the MCP is installed. You will need to restart Claude once completed before you can begin using the MCP. You can verify it's installed with the command /mcp.

OpenAI Codex

Open up the Codex application and copy and paste the following into the prompt. Make sure you replace the {YOUR_API_KEY_HERE} with your api key.

Add the Dewey MCP server to my Codex CLI config at ~/.codex/config.toml. The URL is https://api.deweydata.io/mcp. Store my API key as [API_Key]. The header key is X-API-KEY for the api key and it needs to be sent on every request.

Please store this information as per standard documentation for the codex config

Follow the instructions until the MCP is installed. You may need to restart Codex once completed before you can begin using the MCP. You can verify it's installed with the command /mcp.

Gemini CLI

Open up Gemini and copy and paste the following into the prompt. Make sure you replace the {YOUR_API_KEY_HERE} with your api key.

Add the Dewey MCP server to my Gemini CLI configuration (its possible the config file doesn't exist). The URL is https://api.deweydata.io/mcp and my API key is [YOUR_API_KEY]. Update my ~/.gemini/settings.json using the httpUrl and headers format.

Follow the instructions until the MCP is installed. You will need to restart Gemini once completed before you can begin using the MCP. You can verify it's installed with the command /mcp.

Available Tools

The Dewey MCP server exposes 9 tools across three categories:

Search & Discovery

Tool	Description
`search_datasets`	Keyword + trigram search over datasets. Supports filters for category, container, data partner, region, and download/sample availability. Best when you know specific terms or dataset names.
`semantically_search_datasets`	Vector-based semantic search using cosine similarity across dataset name, summary, columns, and attributes. Best for concept-based queries (e.g., "foot traffic near retail stores").
`list_categories`	Lists all dataset categories available to your account, with dataset counts per category.
`list_data_partners`	Lists all data partners and their dataset containers with per-container dataset counts. Optionally filter to partners where you have download access.

Dataset Details

Tool	Description
`get_dataset_details`	Full metadata for a dataset by slug: description, provider info, access permissions, and optional column metadata at `none`, `minimal`, or `full` depth.
`get_dataset_schema`	Compact schema view: column names, types, descriptions, partition info, and total column count.
`get_related_datasets`	Returns supplementary datasets, siblings within the same container, and joinable datasets with labeled join keys.

Access & Sampling

Tool	Description
`get_download_info`	Download-focused metadata: permissions, file type, size and row estimates, partition range details, customization requirements, and documentation links.
`sample_dataset`	Fetches actual sample rows from a dataset. Select specific columns, limit row count (up to 2,000 rows), and return data as JSON or CSV.

Example Prompts

Once the Dewey MCP is connected, try asking your AI assistant:

"Search for consumer transaction datasets covering 2023–2024."
"What columns are in the SafeGraph weekly patterns dataset?"
"Show me a sample of 10 rows from the ATTOM property data."
"Find datasets related to foot traffic that I can join with demographic data."
"List all employment and labor market datasets I have access to."
"What file format does the Veraset movement data come in, and how large is it?"
"Are there any real estate datasets available for download right now?"
"Show me the schema for the LinkUp job postings dataset."

Tips & Troubleshooting

Security

Always store your API key as an environment variable — never hardcode it in config files or commit it to source control.

Authentication errors

Verify your API key is still valid in your Dewey account under Connections.
If your key was regenerated, update the DEWEY_API_KEY environment variable and restart your AI tool.

Connection not appearing

Run /mcp inside Claude Code, Codex, or Gemini CLI to see server status and diagnose connection issues.