Skip to main content
Documentation

Reference

MCP Server

Astero exposes its bot data and write actions as a Model Context Protocol (MCP) server. Claude Desktop, ChatGPT Operator, custom LLM agents — anything speaking JSON-RPC 2.0 over HTTP with a Bearer token can read your bot state and trigger safe actions on your behalf.

Endpoint

POST https://astero.gg/api/mcp-server
Authorization: Bearer wiz_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

One HTTP endpoint, JSON-RPC 2.0 framing, Bearer auth via an Astero API key (manage from /dashboard/settings). Per-tool scope enforced ; tenant scoping via bot.userId === authCtx.userId at every call. Rate limit : 60 requests / minute / IP.

Tools exposed

15 tools across 6 categories (verified in packages/astero-mcp-server/tools/) :

ticket.* — Support tickets

read + write
ticket.listreadList tickets for a bot, optionally filtered by guild and status.
ticket.getreadFetch a single ticket + transcript metadata.
ticket.getTranscriptreadFetch the rendered HTML transcript of a ticket.
ticket.closewriteClose a ticket with a reason.

mod.* — Moderation

read + write
mod.listCasesreadList moderation cases (warn, kick, ban, mute) for a user or guild.
mod.warnUserwriteIssue a warning against a user.
mod.kickUserwriteKick a user from a guild.
mod.banUserwriteBan a user (optional duration for tempban).

giftCode.* — Creator gift codes

read + write
giftCode.listreadList existing gift codes + redemption status.
giftCode.generatewriteCreate a new gift code with rewards (Role / TempRole / XP / Currency).
giftCode.revokewriteRevoke an active gift code.

stats.* — Bot statistics

read
stats.getBotSummaryreadBot summary : guild count, commands run, errors, plan tier.
stats.getOwnSubscriptionreadYour current Astero plan + AI token quota + next renewal.

analytics.* — Engagement

read
analytics.getActivityreadActivity timeline : messages, voice minutes, command usage.

roi.* — Return on investment

read
roi.getSnapshotreadROI metrics : messages generated by bot, members retained, AI tokens used, hours saved.

Claude Desktop integration

Paste in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent for Windows / Linux :

{
  "mcpServers": {
    "astero": {
      "transport": "streamable-http",
      "url": "https://astero.gg/api/mcp-server",
      "headers": {
        "Authorization": "Bearer wiz_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. The 15 tools become available to Claude, scoped to your bots.

Defense in depth

  • ● Rate limiting — 60 req/min/IP at the Express layer
  • ● Bearer auth — Astero API keys with read / write / admin scopes
  • ● Scope enforcement — every tool declares requiredScope ; admin > write > read hierarchy
  • ● Tenant scoping — every tool handler scopes by bot.userId === authCtx.userId
  • ● Body cap — 1 MB request body limit
  • ● JSON-RPC error frames — errors return HTTP 200 with error object (per spec)

Consuming external MCP servers

A separate feature — your bot can also consume third-party MCP servers (call their tools from your custom commands or workflows). Manage from /dashboard/[guildId]/mcp. This is the /api/mcp installer, distinct from the /api/mcp-server endpoint above which exposes Astero to LLM agents. Plan-gated : MCP installs require Creator Edition or higher (see /docs/plans for limits).

Want to extend with custom triggers ? See the Connector Spec v1.

Beta