MCP · Streamable HTTP

Modly MCP Server for Discord

Connect an AI agent to your Discord server’s Modly modules, settings, XP leaderboard and moderation history. Hosted Streamable HTTP with server-bound API keys.

https://modly.cc/api/mcp

Connect in three steps

Sign in with Discord, choose a server you manage and open Developer API.
Create an expiring key with read:modules and read:config. Add read:leveling or read:moderation only when needed. Copy the key once; it is not shown again.
Configure a client below, reconnect, then ask it to review your server setup. Use the review_server_setup prompt if your client supports MCP prompts.

Codex

Add this to ~/.codex/config.toml. Set MODLY_API_KEY in the environment that starts Codex. The token is read from that variable, not from this file.

[mcp_servers.modly]
url = "https://modly.cc/api/mcp"
bearer_token_env_var = "MODLY_API_KEY"

VS Code

Save as .vscode/mcp.json. VS Code prompts for the key as a password. Start the server from the MCP configuration and use Agent mode.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "modly-api-key",
      "description": "Modly server API key",
      "password": true
    }
  ],
  "servers": {
    "modly": {
      "type": "http",
      "url": "https://modly.cc/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:modly-api-key}"
      }
    }
  }
}

Tools and permissions

Only tools permitted by the key appear in tools/list. Any valid key can read basic server metadata. A write:config key can replace configurations; grant it deliberately and require your agent to ask before changes. Tool annotations guide clients but do not replace client approval controls.

Configuration writes also check the key creator’s current Discord management permissions and role hierarchy. Referenced roles and channels must belong to the key’s server. If Discord cannot verify these checks, writes fail closed with forbidden. Grants also cannot add permissions the issuer does not have.

Tool	Scope	Purpose
get_server	—	Server identity, locale and tier
list_modules	read:modules	Module availability and enabled state
get_module_config	read:config	Complete current config and revision
get_module_schema	read:config	JSON Schema from the module validator
get_leaderboard	read:leveling	Paginated XP leaderboard
get_moderation_cases	read:moderation	Filtered moderation history
update_module_config	write:config	Validated, audited replacement with expectedRevision

A useful first conversation

Ask: “Review my enabled Modly modules and leveling settings. Propose one improvement, explain the effect and wait for my approval.” The agent should read the current configuration and schema before proposing a complete replacement. Revisions prevent lost updates. Server settings and moderation reasons remain untrusted data, not instructions.

Troubleshooting

401: Check the bearer header, expiry and revocation. OAuth login is not supported; use a dashboard API key and a client that accepts bearer headers.
Missing tool: Add its scope to a new key and reconnect. Keys are limited to one server.
429: REST and MCP share the per-key quota: 60 requests/minute on Free, 600 on Premium. Honor Retry-After before retrying.
conflict: Read the current configuration again, review the differences and use its new revision. Do not blindly retry an old replacement.
The endpoint uses stateless Streamable HTTP with JSON responses. There is no persistent SSE stream or session ID; authenticated GET/DELETE return 405. JSON-RPC batching is unsupported. Protocol negotiation and validation use the official MCP SDK.

API reference · Developers