---
title: "Walnut MCP Server — Connect Demo Analytics to Claude, Cursor & VS Code"
slug: "/help/api/mcp-server"
topic: "api"
last_updated: "2026-07-29T09:23:23.104Z"
---

# Overview

The **Walnut MCP Server** lets AI assistants like Claude Desktop, Cursor, and VS Code query your demo analytics data directly. It wraps the [Walnut Customer Data API](/help/api/customer-data-api) and exposes it as [Model Context Protocol](https://modelcontextprotocol.io) tools, so you can ask your AI assistant natural-language questions about demo sessions and get answers grounded in real Walnut data.

Use it to:

- Ask Claude or Cursor to summarize this week's demo performance without leaving your editor
- Build agentic workflows that pull demo session data as context
- Prototype dashboards and reports against Walnut data using an LLM

:::note[Good to know]

The MCP server is a thin bridge — all data still flows through the Customer Data API and requires an `x-api-key`. Rate limits, field definitions, and the 1,000-row-per-request cap all apply as documented in the [Customer Data API reference](/help/api/customer-data-api).

:::

---

# Before You Start

Before installing the Walnut MCP Server, make sure you have:

- **A Walnut Customer Data API key.** Provided by your Walnut account representative. There is no self-service key rotation.
- **Node.js 18 or later.** Required for the built-in `fetch` API.
- **An MCP-compatible client.** Claude Desktop, Cursor, VS Code with Copilot Chat, or any other client that supports MCP.

---

# Available Tools

The server registers three tools with your LLM client:

| Tool | Description |
| --- | --- |
| `walnut_health_check` | Verifies API connectivity and that your API key is valid. |
| `walnut_get_demo_sessions` | Queries demo sessions with filtering, grouping, and pagination. Wraps `GET /demo-sessions`. |
| `walnut_get_demo_sessions_summary` | Returns a high-level snapshot: totals, averages, top demos, top countries. Wraps `GET /demo-sessions/summary`. |

Your LLM client discovers these tools automatically once the server is connected.

---

# Install and Run

1.  Clone or download the `walnut-mcp-server` package from the Walnut monorepo.
2.  Install dependencies and build:

    ```bash
    cd walnut-mcp-server
    npm install
    npm run build
    ```

3.  Choose a transport:

    **stdio (recommended for Claude Desktop and Cursor):**

    ```bash
    WALNUT_API_KEY=your-key node dist/index.js
    ```

    **HTTP (stateless, one MCP server per request):**

    ```bash
    WALNUT_API_KEY=your-key node dist/index.js --http
    # POST http://localhost:3001/mcp
    ```

---

# Environment Variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `WALNUT_API_KEY` | Yes | — | Your Walnut Customer Data API key. |
| `PORT` | No | `3001` | HTTP server port (HTTP mode only). |

If `WALNUT_API_KEY` is missing, the server exits with an error prompting you to contact your Walnut account representative.

---

# Connect to Common Clients

## Claude Desktop

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "walnut": {
      "command": "node",
      "args": ["/absolute/path/to/walnut-mcp-server/dist/index.js"],
      "env": { "WALNUT_API_KEY": "your-key" }
    }
  }
}
```

Restart Claude Desktop. The Walnut tools will appear in the tools menu.

## Cursor / VS Code

Point your MCP client configuration at the same `dist/index.js` entry point, or run the HTTP mode and configure the client to POST to `http://localhost:3001/mcp`.

---

# Example Prompts

Once connected, you can ask your assistant questions like:

- "Check that my Walnut API key still works." → calls `walnut_health_check`.
- "How many demo sessions did we have last week, broken down by user type?" → calls `walnut_get_demo_sessions` with `group_by=date,user_type`.
- "Give me a summary of our top demos and top countries for the last 30 days." → calls `walnut_get_demo_sessions_summary` with a date range.

The assistant will format the response for you and can chain follow-up queries against the same data.

---

# Limitations

- **Read-only.** The MCP server exposes the same read-only endpoints as the Customer Data API. There are no write tools.
- **Demo session data only.** Additional data types (demo metadata, playlist sessions, admin analytics) will be added as they become available in the underlying API.
- **API key changes may take up to 5 minutes** to propagate due to authorization caching on the API side.
- **Rate limits apply.** 50 requests/second sustained, 100 requests/second burst, 1,000 rows max per request. If you hit `429 Too Many Requests`, the server surfaces the error to the LLM client.

---

# Support

For API key provisioning, replacement, or rate limit changes, contact your Walnut account representative. For issues with the MCP server itself, include the transport (stdio or HTTP), the tool name that failed, and any error message returned to your MCP client.