Getting Started

Watt Data provides MCP (Model Context Protocol) tools for building data enrichment and audience discovery workflows. These tools can be used directly via API, through Claude AI's native connector integration, or through automation platforms.

Endpoints

Watt Data MCP is available at the following endpoints:

Your current endpoint: https://api.wattdata.ai/mcp

Versioned Paths (Recommended):

• /v1/mcp - Accepts both OAuth and M2M authentication
• /v1/mcp/m2m - M2M authentication only

Legacy Paths (Supported for backward compatibility):

• /mcp - Same authentication as /v1/mcp
• /mcp/m2m - Same authentication as /v1/mcp/m2m

Use versioned endpoints for new integrations to ensure stability across API updates.

Integration with Claude

The simplest way to use Watt Data is through Claude's native MCP connector integration. This allows Claude to directly access Watt Data tools within conversations.

For Individual Users (Pro/Max Plans)

1. Navigate to Settings > Connectors in Claude
2. Select Add custom connector
3. Enter the MCP server URL: https://api.wattdata.ai/mcp
4. Click Add to complete setup

For Team and Enterprise Plans

Team and Enterprise plans require an admin to first enable the connector for the organization:

Admin Setup (Required First):

1. Navigate to Admin settings > Connectors
2. Select Add custom connector
3. Enter the MCP server URL: https://api.wattdata.ai/mcp
4. Click Add to make the connector available to team members

Member Connection (After Admin Setup):

1. Go to Settings > Connectors
2. Find the Watt Data connector (marked with "Custom" label)
3. Click Connect to authenticate and enable it

Using Connectors in Conversations

Once configured, enable connectors in any conversation:

1. Click the + button in the lower left of the chat interface
2. Select Connectors
3. Enable the Watt Data connector for that conversation

Claude can then use Watt Data tools to answer questions about audience building, identity enrichment, and customer analysis.

Authentication

OAuth (User Authentication)

Authorization: Bearer <oauth_token>

Use OAuth for end-user applications with Clerk authentication.

API Key (Machine-to-Machine)

Use API keys for server-to-server integrations and automation.

Setup:

1. Go to your API Keys dashboard to create an API key
2. Copy the key (starts with watt_) — it is only shown once

Authentication Methods:

You can send your API key in any of these ways:

# Option 1: x-api-key header (recommended)
curl -H "x-api-key: watt_..." https://api.wattdata.ai/v1/mcp

# Option 2: Basic auth with key name and key value
curl -u "my-key-name:watt_..." https://api.wattdata.ai/v1/mcp

# Option 3: Raw key in Authorization header
curl -H "Authorization: Basic watt_..." https://api.wattdata.ai/v1/mcp

Endpoints:

• /v1/mcp - Accepts both OAuth and API key authentication
• /v1/mcp/m2m - API key authentication only

Common Features

Workflow Sessions

All tools accept an optional workflow_id parameter (UUID format) for:

• Deterministic Results: Same workflow_id returns consistent results across calls
• Feedback Correlation: Link feedback to specific query sessions
• Session Tracking: Group related tool calls for analytics

Export Formats

Three tools support large result exports (resolve_identities, get_person, find_persons):

• none (default) - Returns sample results in response
• csv - Comma-separated values
• json - Single JSON array
• jsonl - Newline-delimited JSON (streaming-friendly)

Export URLs are valid for 1 hour and recommended for result sets >100,000 records.

Tracing

Every tool response includes a tool_trace_id for debugging and support requests.

Integration Approaches

MCP Client Integration

Use Watt Data through an LLM client like Claude Desktop or Claude.ai. The LLM handles query planning, parameter selection, and result interpretation naturally.

Direct API Integration

For programmatic access, use Watt Data as a JSON-RPC API layer. See the API Integration guide for critical best practices on data volatility and caching requirements.

Next Steps

• API Integration - Critical caching and data volatility guidelines for API integrators
• MCP Tool Reference - Detailed documentation for all tools
• Guides - End-to-end workflow examples