MCP API (Model Context Protocol)

Kotbo’s MCP (Model Context Protocol) support lets you connect an external AI assistant (such as Claude.ai or ChatGPT) directly to your Discord server. The AI can then read data or carry out moderation actions, within strictly defined permissions.

Beta feature

The MCP integration is currently in testing. The features and the connection interface may still change.

---

What is MCP?

MCP is an open standard that lets an AI model interact with external tools and databases. Thanks to the MCP server Kotbo exposes, your AI can become a powerful administration or community assistant, with real-time context on what is happening on your server.

---

Step 1: create an MCP access key

To connect an AI, you need to generate dedicated credentials from the Kotbo dashboard.

1. Go to Configuration → MCP API (Open the MCP API ↗).
2. Click the New key button in the top right.
3. Enter a key name so you can identify it easily (for example Claude Web, ChatGPT Staff).
4. Configure the key’s permissions. Only tick what the intended use actually requires.

Read permissions (READ)

• Server Stats: members, messages, activity.
• Members & Messages: profiles, recent messages, reading forums and posts.
• Sanctions: list and history.
• Staff: staff list and profiles.
• Tickets: list of open tickets.
• Community: leaderboards, suggestions, events, quests, reputation, custom onboarding, clan bets and debts.
• Economy: RPG profiles, shop, marketplace, economic leaderboards.
• Moderation: AutoMod, banned words, auto responses, CodePolice.
• Analytics: per-channel stats, hourly heatmap, Pulse, predictions.
• Read automations: view automations, their run history and the catalogue of available blocks.

Write permissions (WRITE)

Sensitive permissions

Write permissions let the AI make real changes to your server. Be careful.

• Sanction: apply or remove sanctions via the AI.
• Manage Messages: send, edit or delete messages, and manage forums, posts and tags.
• Manage Tickets: reply to and close tickets via the AI.
• Manage Community: answer suggestions, manage events and giveaways, the custom onboarding pipeline, settle and void clan bets.
• Manage Members: moderator notes, adding and removing roles, levels, invites.
• Manage automations: create, edit, enable and delete automations.

The permission that acts without you

Manage automations is the only one that leaves a lasting trace: an automation the AI enables then acts on its own, moderation included. Grant it only to a trusted key.

5. Click Generate Key.
6. IMPORTANT: a window appears with your Client ID and your Client Secret (which starts with mcp_). Copy and store this information straight away. The Client Secret will never be shown in plain text again.

A key follows its holder

A key is tied to the account that created it: it stops answering if that account loses access to the server.

Keys created before this rule carry the No owner label: it keeps answering even if whoever uses it loses access to the server. Revoke and recreate it so it follows its holder.

---

Step 2: configure your AI client

Pick your AI assistant to see the matching setup instructions:

Claude.ai

Anthropic’s Claude supports remote MCP servers as custom connectors.

1. Open Claude.ai and go to your settings by clicking your profile, then go to Customize → Connectors (or click the button available in Kotbo’s connection help).
2. Click the + button, then choose Add custom connector.
3. Enter the following details:
   • Name: Kotbo
   • URL: in the Kotbo dashboard, on the row for your MCP key, click Generate the direct Claude URL and copy it. Paste that long signed URL into Claude.
   • Note: leave the optional fields (Client ID, Client Secret, Advanced) empty when you use the direct URL.
4. Click Add. Claude is now connected to Kotbo.

If authorisation fails

If Claude shows an “Authorization failed” error after connecting, use the direct Claude URL generated by the dashboard rather than the standard MCP server URL. That signed URL works around Claude’s network authorisation blocks.

ChatGPT

OpenAI’s ChatGPT lets you add remote MCP servers once developer mode is enabled.

1. Open ChatGPT on the web.
2. Go to your settings: Settings → Apps → Advanced settings.
3. Turn on the Developer mode toggle.
4. Click Create app and select the option to add a remote MCP server.
5. Enter the connection settings:
   • App name: Kotbo
   • MCP server URL: copy the MCP server URL (endpoint URL) shown at the top of the MCP API page on your Kotbo dashboard (in the format https://api.kotbo.fr/api/mcp/SERVER_ID).
   • Authentication: select OAuth or Mixed Authentication.
6. Confirm. The first time you chat with ChatGPT and it calls the bot, a Kotbo authorisation window opens: enter your MCP access key to finish linking the two.

---

Custom integrations (API & Gemini)

If you are building your own MCP client (for example with Google’s MCP SDKs for Gemini, or in Python/TypeScript):

Authentication works by passing the access key as a Bearer token in the header of your HTTP requests.

Example JSON configuration for an MCP server:

{
  "type": "mcp_server",
  "name": "Kotbo",
  "url": "https://api-kotbo-url/api/mcp/YOUR_SERVER_ID",
  "headers": {
    "Authorization": "Bearer mcp_YOUR_CLIENT_SECRET"
  }
}

(Replace mcp_YOUR_CLIENT_SECRET with the full Client Secret you copied when you created the key.)

---

Diagnostics and logs

If the AI cannot read information, or if requests are failing, you can check the logs in real time.

1. Go to Configuration → MCP API.
2. Next to your endpoint URL, click the Logs button.
3. You will see every recent incoming connection, the methods called (for example listTools, callTool) and any errors the bot returned.