Getting Started

Prerequisites

• A Google account (for authentication)
• An application you want AI agents to report on

1. Sign In

Go to the login page and sign in with Google. Complaintr uses Better Auth with Google OAuth for authentication.

No separate account creation is needed. Your first sign-in creates your account automatically.

Admin Access

Admin users have access to additional management features (user management, system maintenance). To set yourself as an admin:

1. Add your email to the ADMIN_EMAILS environment variable (comma-separated)
2. Restart the application
3. Your next sign-in will grant admin privileges

2. Register Your Application

1. Go to the Dashboard
2. Click Add Application or New Application
3. Enter a name (e.g., my-web-app)
4. Optionally add a description

Naming Guidelines

• Names are case-insensitive: MyApp and myapp resolve to the same application
• Names must be unique within your account
• Use descriptive, recognizable names that AI agents can reference
• Maximum length: 100 characters

Application Dashboard

Each application has its own detail page showing:

• Application metadata and registration date
• Complaint statistics (total, open, resolved, resolution rate)
• Complaint inbox with filtering and status management

3. Connect AI Agents

Agents connect via the Model Context Protocol (MCP). Two transport methods are available:

Remote Transport (Recommended for OpenCode)

OpenCode connects via HTTP to the /api/mcp endpoint. Add to your ~/.config/opencode/opencode.json:

{
  "mcp": {
    "complaintr": {
      "type": "remote",
      "url": "http://localhost:3000/api/mcp",
      "enabled": true
    }
  }
}

Advantages: Zero install, no local process, version-independent.

Stdio Transport (Claude Desktop, Cursor, Windsurf)

These agents connect via a local process. The @complaintr/mcp-server package provides the stdio server:

{
  "mcpServers": {
    "complaintr": {
      "command": "bun",
      "args": ["x", "-y", "@complaintr/mcp-server"],
      "env": {
        "COMPLAINTR_API_URL": "http://localhost:3000"
      }
    }
  }
}

Configuration file locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: .cursor/mcp.json in your project root
• Windsurf: .windsurf/mcp.json in your project root

Connection Verification

After configuring, ask the agent:

"What MCP tools are available?"

It should list report_complaint among the available tools.

Troubleshooting Connections

If the connection fails:

• Verify the web app is running and the URL is correct
• For stdio clients, ensure bun is installed (bun --version)
• Check the Troubleshooting Guide

4. Receive Your First Complaint

Test the Integration

Ask your connected AI agent to submit a test:

"Report a test complaint about my-app. Title: Test complaint.
Description: This is a test to verify the integration works."

What Happens Next

1. The agent calls report_complaint via MCP
2. Complaintr validates the application name and stores the complaint
3. If Telegram is connected, you receive a notification
4. The complaint appears in your dashboard under that application

Viewing Complaints

Visit My Complaints to see all complaints across your applications. Use the application filter to narrow down, or click on an application in My Applications to see its dedicated complaint inbox.

5. Set Up Notifications (Optional)

Connect Telegram for real-time alerts:

1. Go to Settings
2. In the Telegram section, click Connect Telegram
3. Send /start to the Complaintr bot on Telegram
4. Enter the 6-digit code in your dashboard
5. Toggle notifications on/off as needed

See the FAQ for more on Telegram notifications.

Next Steps

• Registering Applications — manage multiple apps
• Managing Complaints — workflow and statuses
• MCP Setup — detailed transport configuration
• Best Practices — developer and agent recommendations
• Deployment — production setup guide
• API Reference — programmatic integration