MCP Server for AI Agents

Let Claude, ChatGPT, and other AI agents query your analytics directly.

Overview

Echelon Analytics includes a Model Context Protocol (MCP) server that lets AI agents query your analytics via the REST API. Point it at any Echelon instance — local or remote, public or authenticated.

Quick Start

# Public instance (no token needed)
ECHELON_URL=https://ea.islets.app deno task mcp

# Local instance with authentication
ECHELON_URL=http://localhost:1947 ECHELON_SECRET=your-token deno task mcp

How It Works

The MCP server is a thin bridge between AI agents and the Echelon REST API:

1. You set ECHELON_URL to point at any Echelon Analytics instance
2. The MCP server starts and connects to the AI agent via stdio (JSON-RPC)
3. When you ask a question, the AI agent picks the right MCP tool
4. The MCP server calls the corresponding GET /api/* endpoint (read-only — never POST, PATCH, or DELETE)
5. The API response is returned to the agent, which summarizes it for you

For authenticated instances, set ECHELON_SECRET — the server passes it as a Bearer token for read-only access. The server only ever calls GET endpoints; it cannot create, modify, or delete any data even if the token has write privileges. For PUBLIC_MODE instances (like the public demo), no token is needed.

Setup

1. Claude Code

The repo includes .claude/settings.json which auto-registers the MCP server. By default it points at the public demo instance. To use your own instance, edit the env block:

{
  "mcpServers": {
    "echelon-analytics": {
      "command": "deno",
      "args": ["task", "mcp"],
      "cwd": "echelon-analytics",
      "env": {
        "ECHELON_URL": "https://your-instance.example.com",
        "ECHELON_SECRET": "your-api-token"
      }
    }
  }
}

Then just open the project and ask questions — the tools are available automatically.

2. Claude Desktop

Add the server to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "echelon-analytics": {
      "command": "deno",
      "args": ["task", "mcp"],
      "cwd": "/path/to/echelon-analytics",
      "env": {
        "ECHELON_URL": "https://your-instance.example.com",
        "ECHELON_SECRET": "your-api-token"
      }
    }
  }
}

Restart Claude Desktop. You'll see the MCP tools icon in the chat input. Ask a question like "What are my top pages?" and Claude will use the analytics tools to answer.

3. Any MCP Client (stdio)

The server speaks JSON-RPC over stdio. Point any MCP-compatible client at it:

# Public instance
ECHELON_URL=https://ea.islets.app deno run -A mcp-server.ts

# Authenticated instance
ECHELON_URL=https://echelon.example.com ECHELON_SECRET=your-token deno run -A mcp-server.ts

Send a tools/list request to discover available tools, then tools/call with the tool name and parameters.

What You Can Ask

Once connected, try natural language questions. The AI agent picks the right tool automatically:

Example Conversation

Here's what a typical session looks like in Claude Code or Claude Desktop:

You: How's echelon-analytics doing this week?

Agent: [calls analytics_overview with site_id="echelon-analytics", days=7]

Your site had 342 visits from 218 unique visitors this week.
Top pages: /admin (89 views), /features.html (54), /installation.html (41).
Traffic sources: 45% direct, 28% search, 18% social, 9% referral.
Busiest day was Tuesday with 73 visits.

You: Which campaigns are active?

Agent: [calls list_campaigns]

You have 3 campaigns:
- spring-2026 (active) — "Spring Launch" on site default
- docs-launch (active) — "Documentation Launch" on site echelon-analytics
- old-promo (archived) — "Old Promo" on site default

You: Break down the spring campaign

Agent: [calls analytics_campaign_detail with campaign_id="spring-2026"]

Spring Launch (last 30 days): 156 views, 89 unique visitors.
By source: newsletter (72 views), twitter (48), google (36).
By medium: email (72), social (48), cpc (36).
Top landing page: /sale (94 views), / (38), /pricing (24).

You: Do campaign visitors actually use the dashboard feature we advertised?

Agent: [calls analytics_campaign_events with site_id="my-app", event_type="feature_used"]

Campaign visitors trigger "feature_used" events at a much higher rate:
- spring-2026: 89 visitors, 34 triggered feature_used (38.2% event rate)
- docs-launch: 41 visitors, 22 triggered feature_used (53.7% event rate)
- Organic (no campaign): 218 visitors, 29 triggered feature_used (13.3% event rate)

Your docs-launch campaign drives visitors 4x more likely to use the
feature compared to organic traffic.

You: How's the checkout experiment?

Agent: [calls analytics_experiments with experiment_id="checkout-v2"]

Checkout Redesign — metric: purchase, status: active
- Control (Original): 1,240 impressions, 62 conversions (5.0%)
- Redesign (New Flow): 1,185 impressions, 78 conversions (6.6%)
  Uplift: +31.3% — 95% statistically significant

Available Tools

All 9 tools are read-only and return JSON. The server only calls GET endpoints — it cannot create, modify, or delete any data.

Client Setup Reference

Claude Code

Auto-discovered via .claude/settings.json in the repository — edit ECHELON_URL there to point at your instance.

Claude Desktop

See the config paths and JSON snippet in the Setup section above.

Other MCP Clients

Any MCP-compatible client can connect via stdio transport. Set ECHELON_URL (and optionally ECHELON_SECRET) as environment variables.

Architecture

API-Backed

The MCP server calls the Echelon REST API over HTTP — it never touches the database directly. This means:

• Works with any instance (local, remote, Docker, cloud)
• Respects PUBLIC_MODE, anonymization, and access controls
• No local database file needed
• Same data as the admin dashboard — always live

Read-Only by Design

The server only calls GET endpoints. It never sends POST, PATCH, or DELETE requests — it cannot create, modify, or delete any data even if the token has write privileges. This is a deliberate constraint to maintain data authenticity while learning MCP usage patterns. Write tools may be added in a future version.

Transport

Uses stdio transport (JSON-RPC over stdin/stdout). Logging goes to stderr to avoid interfering with the protocol. Compatible with any MCP client that supports stdio.

Dependencies

• @modelcontextprotocol/sdk — official MCP SDK
• zod — parameter validation

Configuration

🤖 "The MCP server calls the same REST API as the admin dashboard — same data, same filters, same anonymization. Ask your AI agent 'how's my site doing?' and it gets live results." -🦭

Database Portability

The MCP server queries your analytics through the REST API, and all that data lives in a single SQLite file. Copy echelon.db to another machine, start an Echelon instance pointing at it, and query it with any MCP client. Your analytics travel with you.

See Portable Data for details on the database schema, example SQL queries, and data lifecycle.