AI Agents

The Dregs MCP server lets AI agents work in your Dregs account. An agent connected through it can investigate a scored identity and the observations behind its scores, follow its links to related accounts and devices, review and triage escalations, and tune the badge and escalation rules that label and flag identities. It uses the Model Context Protocol (MCP), so it works with Claude, ChatGPT, Codex, Cursor, VS Code, and any other client that speaks MCP over HTTP.

The Dregs MCP Endpoint

The server is part of the Dregs service and runs alongside the REST API. There is nothing to install on your side. Setup snippets for each client, the Claude Code plugin, and the metadata behind Dregs's directory listings are kept in the public dregs-mcp repository; this chapter is the maintained guide.

OAuth or an MCP Token

OAuth is the easiest way to connect. When a client that supports MCP OAuth first talks to the server, it opens your browser at Dregs. You sign in to the dashboard if you are not already, and an approval page shows which application is connecting, where it will send its response, and the team it will act in. If you belong to more than one team, you choose the team on that page. Approving issues the client short-lived access tokens that it refreshes on its own, and the connection appears under Settings → AI Agents → Connections, where you can revoke it at any time.

MCP tokens are for clients that cannot complete an OAuth sign-in, and for scripted or headless agents. Create one under Settings → AI Agents → Tokens, give it a name that says where it will be used, and copy it right away; it is shown only once. Send it as a Bearer header:

Authorization: Bearer dmcp_your_token_here

A token acts as you within the team where you created it, with your dashboard role, and works only at the MCP endpoint: it is refused everywhere else in the API. Treat it like a password, use one token per agent or machine, and revoke tokens you no longer use. Changing your password revokes your tokens, and leaving a team revokes the tokens and connections you held there.

Connecting Claude Code to Dregs

The quickest way is the plugin from the dregs-mcp repository, which registers the Dregs MCP server and adds a few skills that encode a sensible investigation workflow. In Claude Code:

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

Then run /mcp, pick dregs, and approve the 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 walks 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 dmcp_your_token_here"

The equivalent project-level .mcp.json:

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

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 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, reading the token from an environment variable so it never lands in the file:

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

Connecting Cursor to Dregs

Add the server 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}" } to the server entry and set DREGS_MCP_TOKEN in the environment before starting Cursor. The dregs-mcp repository has a one-click install link as well.

Connecting VS Code to Dregs

Run MCP: Add Server from the Command Palette and enter the URL, or add the server to .vscode/mcp.json:

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

To use an MCP token, declare a secret input and reference it in the header. VS Code prompts for the value once and stores it in its secret storage, so the token never appears in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "dregs-token",
      "description": "Dregs MCP token",
      "password": true
    }
  ],
  "servers": {
    "dregs": {
      "type": "http",
      "url": "https://dregs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:dregs-token}"
      }
    }
  }
}

Connecting Other MCP Clients to Dregs

Any client that supports remote servers over Streamable HTTP connects the same way: give it the URL and either approve the OAuth connection or supply a token header. 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 dmcp_your_token_here"]
    }
  }
}

What an Agent Can Do

The server exposes the investigative and rule-tuning parts of the dashboard. Clients fetch the live tool list when they connect, so this table is a map rather than the source of truth. Reads are available to every team member; writes follow your dashboard role, and the tools that need the admin role are marked.

get_documentation returns chapters of this manual as text, so an agent can read about scoring before interpreting a score, or about escalations before writing a rule. The server's instructions tell it to do exactly that.

Some things are left to humans on purpose. An agent cannot create or edit notification channels or see their secrets, manage your team, API 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 you before writes and deletes, and the server's instructions tell agents to describe any change and confirm with you before making it.

Working Safely with an Agent

• 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, and treat an attribute that addresses the agent as a signal in its own right.
• 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. Deleting a rule cannot be undone from the API.
• Scope your access. Connect with OAuth where you can, since access tokens are short-lived and the connection is visible under Settings → AI Agents. Use one MCP token per agent or machine, name tokens clearly, and revoke any you no longer use.
• Results link back. Identities, devices, escalations, and rules come back with a dashboardUrl, so you can open the same record in Dregs and check the agent's reading against the dashboard.

Troubleshooting

• The first request answers 401. That is how OAuth discovery starts: the server's 401 carries a WWW-Authenticate header pointing at its authorization metadata, and the client follows it to the sign-in. A 401 that repeats after you have approved the connection means the connection was revoked or the token is wrong.
• The agent is working in the wrong team. An OAuth connection acts in the team you chose on the approval page, and a token in the team where it was created. Disconnect and reconnect, choosing the right team, or create a token in the right team.
• A write is refused with a role message. The connected user is not an admin on that team. Reads still work; an admin has to make the change, in the dashboard or through their own connection.
• Every call answers 403 with mcp_disabled. Your plan does not include AI agent access. See pricing or contact us.
• Tokens stopped working after a password change. That is by design; create a new token.
• Stale or missing tools. Clients cache the tool list when they connect. After a reconnect, restart the client or ask it to refresh its MCP servers.

For anything else, email support@dregs.com. Security concerns about the MCP server or its OAuth flow go to security@dregs.com.