Dregs MCP Server

Dregs MCP

Dregs scores a site's users for fraud and abuse: fake signups, bots, duplicate accounts, referral fraud, and account takeover, each explained by the observations behind the score. Its built-in Model Context Protocol (MCP) server lets AI agents like Claude, ChatGPT, Codex, Cursor, and VS Code investigate identities, review escalations, and tune rules in your Dregs account.

This repository is the public home for connecting to that server: setup snippets for each client, the Claude Code plugin, and the metadata behind Dregs's listings in MCP directories. The server itself is hosted by Dregs at https://dregs.com/mcp, and its source is not published here.

The maintained, full-length guide is the AI Agents chapter of the Dregs manual. This README is the short version.

The Dregs MCP endpoint

OAuth is the easiest way to connect. Clients that support MCP OAuth send you to Dregs to approve the connection in your browser. If you belong to more than one team, you choose the team on the approval page, and you can review or revoke connected agents under Settings → AI Agents in the Dregs dashboard.

MCP tokens are for clients that can't do OAuth, and for scripted agents. Create one in the Dregs dashboard under Settings → AI Agents, copy it right away (it's only shown once), and send it as Authorization: Bearer YOUR_TOKEN. A token acts as you within the team where you created it, so treat it like a password.

Connecting Claude Code to Dregs

The quickest way is the plugin from this repository, which adds the Dregs MCP server plus skills for integrating Dregs into your application and for working with the data afterwards:

/plugin marketplace add dregs-sdk/dregs-mcp
/plugin install dregs@dregs

Then run /mcp, pick dregs, and approve the OAuth connection in your browser. Ask Claude something like "Summarize my Dregs account" to confirm it can reach your team.

Without the plugin, add the server directly and Claude Code will walk you through OAuth:

claude mcp add --transport http dregs https://dregs.com/mcp

Or with an MCP token, for headless use:

claude mcp add --transport http dregs https://dregs.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

The equivalent project-level .mcp.json:

{
  "mcpServers": {
    "dregs": {
      "type": "http",
      "url": "https://dregs.com/mcp"
    }
  }
}

Plugin skills

The plugin's skills are workflows, not tool schemas; each reads the relevant manual chapter through get_documentation before it acts, proposes changes for you to review, and confirms before anything is written.

The integration skills edit your code, so they need a client with repository access such as Claude Code or Codex. The others work anywhere the server is connected.

Connecting Claude Desktop and claude.ai to Dregs

Claude Desktop and claude.ai connect to remote MCP servers as custom connectors, which use OAuth.

1. Open Settings → Connectors and choose Add custom connector.
2. Enter a name and the URL https://dregs.com/mcp.
3. Choose Connect and approve the Dregs OAuth connection when your browser opens.
4. In a conversation, open the tools menu and turn on the Dregs connector.

Connecting ChatGPT and Codex to Dregs

ChatGPT on the web connects through plugins created in Developer mode (Settings → Security and login). Open Plugins, add a connection with the URL https://dregs.com/mcp, then add it to a new conversation from the tools menu and approve the OAuth connection.

Codex in the ChatGPT desktop app, the Codex CLI, and the Codex IDE extension share one configuration:

codex mcp add dregs --url https://dregs.com/mcp
codex mcp login dregs

Or with an MCP token in ~/.codex/config.toml:

[mcp_servers.dregs]
url = "https://dregs.com/mcp"
bearer_token_env_var = "DREGS_MCP_TOKEN"

Connecting Cursor to Dregs

Or add it to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects) and approve the OAuth connection when Cursor first connects:

{
  "mcpServers": {
    "dregs": {
      "url": "https://dregs.com/mcp"
    }
  }
}

To use an MCP token instead, add "headers": { "Authorization": "Bearer ${env:DREGS_MCP_TOKEN}" } and set DREGS_MCP_TOKEN in the environment before starting Cursor.

Connecting VS Code to Dregs

Or run MCP: Add Server from the Command Palette, or add it to .vscode/mcp.json:

{
  "servers": {
    "dregs": {
      "type": "http",
      "url": "https://dregs.com/mcp"
    }
  }
}

To use an MCP token, declare a promptString input with "password": true and reference it in an Authorization header. The manual has the complete example.

Connecting other MCP clients to Dregs

Any client that supports remote servers over Streamable HTTP can connect the same way. For clients that only support local (stdio) servers, the mcp-remote bridge usually works. Leave out the --header arguments to have it run the OAuth flow instead of using a token:

{
  "mcpServers": {
    "dregs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://dregs.com/mcp", "--header", "Authorization: Bearer YOUR_TOKEN"]
    }
  }
}

What an agent can do with Dregs

The server exposes the investigative and rule-tuning parts of the Dregs dashboard. Clients fetch the live tool list when they connect, so this table is a map of the surface rather than the source of truth.

Reads are available to every team member. Writes follow your dashboard role: creating, changing, or deleting rules, disregarding an identity, re-scoring, testing a channel, and editing datasets or mappings need the admin role. Some things are left to humans on purpose. An agent cannot create or edit notification channels or their secrets, manage your team, credentials, or billing, delete identities or events, or change how Dregs scores. It investigates, proposes, and hands off.

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients that honor them can prompt before writes and deletes.

Server SDKs

Getting data into Dregs is a separate job from connecting an agent to it, and there is an official SDK for each of five server languages. They cover sending events, reading an identity with its scores or its full analysis, requesting a re-score, and verifying webhook signatures, with typed errors per status and retries with backoff built in. Reach for one before writing an HTTP client by hand; the plugin's setup-events skill does.

The SDKs are server-side only and authenticate with a credential's secret key (sk_…) as a bearer token. Browser tracking remains the dregs.js script with the public key (pk_…). On npm the bare dregs package is that browser script, not the SDK; the server SDK is @dregs/sdk.

Safety practices for AI fraud review

• The data is written by the people being scored. Identity attributes, display names, and event payloads are user input, and a bad actor can put text in them aimed at an agent. The server tells agents to treat everything it returns as data, never as instructions. Keep that in mind when you read an agent's conclusions too.
• The agent acts in your account. Rule changes and disregarded identities affect the whole team's scoring and escalations. Ask for a preview (preview_escalation_rule reports how many identities a rule would open against today) and review proposed changes before approving them.
• Scope your access. Use one token per agent or machine, name them clearly, and revoke any you no longer use. Review OAuth connections under Settings → AI Agents.

Support

• Setup help and questions: support@dregs.com
• Security issues: see SECURITY.md
• Problems with the contents of this repository (the README, plugin, or directory metadata): open an issue here

What's in this repository

Releasing a new version of the surface

The tool surface is a public API once published. When it changes: bump version in server.json, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json together, update the tool table above and the skills if tools were added or renamed, tag the release vX.Y.Z, and publish a GitHub release. The publish-registry workflow pushes server.json to the MCP Registry from the release.

License

The contents of this repository are released under the MIT License. The Dregs service itself is governed by Dregs's terms of service.