@riuve/mcp

AI assistant integration for Riuve — connect Claude Desktop, Cursor, Windsurf, and any MCP-compatible client to your event analytics, documentation, and campaigns.

What it does

Riuve MCP exposes your project's analytics and documentation as Model Context Protocol tools. Once connected, your AI assistant can:

• Analyze events — "How many purchases happened last week?"
• Compare periods — "Is signup conversion up or down vs last month?"
• Dig into user journeys — "What did user [email protected] do yesterday?"
• Search documentation — "How do I install the Next.js SDK?"
• Build funnels — "What's the onboarding drop-off rate?"
• Read cohort retention — "How sticky are users from November?"
• List campaigns / chains — read-only access to what's already shipped

All without leaving your editor or chat window.

Install

No install required — the MCP server runs on-demand via npx:

npx @riuve/mcp

You'll never run this directly. Instead, you wire it into your MCP client's configuration file and the client spawns it for you.

Quick start

1. Get an access token

Log in to your Riuve dashboard and go to Settings → MCP Access Tokens. Create a new token and copy it. You'll only see the plaintext value once.

2. Configure your AI client

Open your claude_desktop_config.json:

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

Add:

{
  "mcpServers": {
    "riuve": {
      "command": "npx",
      "args": ["-y", "@riuve/mcp@latest"],
      "env": {
        "RIUVE_API_KEY": "mcp_live_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. In a new conversation, you should see Riuve tools appear in the tool listing.

Open Cursor settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "riuve": {
      "command": "npx",
      "args": ["-y", "@riuve/mcp@latest"],
      "env": {
        "RIUVE_API_KEY": "mcp_live_your_token_here"
      }
    }
  }
}

Reload Cursor. Riuve tools will be available in Composer.

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "riuve": {
      "command": "npx",
      "args": ["-y", "@riuve/mcp@latest"],
      "env": {
        "RIUVE_API_KEY": "mcp_live_your_token_here"
      }
    }
  }
}

Restart Windsurf.

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "riuve": {
      "command": {
        "path": "npx",
        "args": ["-y", "@riuve/mcp@latest"],
        "env": {
          "RIUVE_API_KEY": "mcp_live_your_token_here"
        }
      },
      "settings": {}
    }
  }
}

3. Ask your AI

Try any of these prompts to confirm the integration is live:

"List the available Riuve tools."

"Give me a summary of my project's events over the last 7 days."

"How do I install the Riuve Next.js SDK?"

"Which users had the most events this week?"

Environment variables

| Variable | Required | Default | Description | |----------------------|----------|-----------------------------|-------------| | RIUVE_API_KEY | Yes | — | Project-scoped access token from the dashboard. | | RIUVE_API_URL | No | https://api.riuve.com | Backend URL — override for self-hosted or staging environments. | | RIUVE_TIMEOUT_MS | No | 120000 | Per-request timeout in milliseconds. Analytics queries over long date ranges need headroom — 2 minutes is safe default. | | RIUVE_DEBUG | No | false | Set to 1 or true to emit verbose diagnostics on stderr. |

Tools

The server advertises the full tool list via the standard MCP tools/list request — your AI client picks these up automatically. As of v0.1, the exposed tools are:

Analytics

• get_event_overview — totals, top events, platform + country breakdown
• get_event_trends — daily event counts
• compare_periods — before/after comparison between two time ranges
• get_error_events — error/failure/crash events
• get_top_users — most active users
• get_funnel_analysis — multi-step conversion funnel
• get_retention_cohort — weekly/daily cohort retention
• get_user_journey — single user timeline + profile
• get_event_property_distribution — event breakdown by property
• compare_users — side-by-side user comparison

Documentation

• search_riuve_docs — semantic search over Riuve docs, help center, and SDK READMEs

Campaigns (read-only)

• list_campaigns — most recent campaigns
• list_chains — most recent automation chains

Note on mutations: creating, updating, or deleting campaigns and chains is intentionally not available through MCP in v0.1. Those workflows happen in the Riuve dashboard where the preview → confirm pattern is fully supported.

Troubleshooting

"RIUVE_API_KEY environment variable is required"

Your MCP client is spawning the server but the token isn't reaching it. Double-check:

• The env block in your MCP config is inside the same object as command and args.
• You restarted the MCP client after editing the config file.
• The token string has no accidental whitespace or line breaks.

"Authentication failed" / 401 error

The token exists but the backend rejected it. Possible causes:

• The token was revoked in the dashboard.
• The token expired (if you set an expiry at creation time).
• You copied the token from the wrong project.

Generate a new token from Settings → MCP Access Tokens and replace it in your config.

Tools not showing up in the client

• Verify the client's MCP log pane — it usually shows the server's stderr output, which surfaces startup errors.
• Run RIUVE_DEBUG=1 npx @riuve/mcp in a terminal (with your env var set) to see the server boot sequence directly.
• Check RIUVE_API_URL — if you set a custom URL, make sure it's reachable from your machine.

Network or timeout errors

• Default timeout is 30 seconds. Increase RIUVE_TIMEOUT_MS for very slow queries.
• Check your firewall / proxy settings — the server fetches over HTTPS.

Development

This package is open source (MIT). The code lives at developer/space/mcp in the Riuve monorepo.

cd developer/space/mcp
npm install
npm run build
npm run typecheck

Local testing against a dev backend

export RIUVE_API_URL=http://localhost:3000
export RIUVE_API_KEY=mcp_live_...
export RIUVE_DEBUG=1
node dist/index.js

Then manually send JSON-RPC frames on stdin to exercise the protocol.

License

MIT — see LICENSE.