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 and exposes it as Model Context Protocol 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

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.

---

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:

   cd walnut-mcp-server
   npm install
   npm run build

3. Choose a transport:

   stdio (recommended for Claude Desktop and Cursor):

   WALNUT_API_KEY=your-key node dist/index.js

   HTTP (stateless, one MCP server per request):

   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:

{
  "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.