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, message statistics and overall activity level.
• Members: users’ Discord profiles, search and recent messages.
• Sanctions: the history and list of sanctions applied on the server.
• Staff: the list of team members and their profiles.
• Tickets: viewing open tickets.
• Community: XP leaderboards, suggestions, events, quests and reputation.
• Economy: RPG profiles, inventories, the shop and the marketplace leaderboard.
• Moderation: AutoMod configuration, banned words, automatic replies.
• Analytics: detailed per-channel statistics, activity maps (Pulse), predictions.

Write permissions (WRITE)

Sensitive permissions

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

• Sanction: lets the AI apply or lift sanctions (warnings, bans, and so on).
• Send messages: lets the AI post messages in a Discord channel under the bot’s name.
• Manage tickets: lets the AI reply to tickets and close them.
• Manage community: lets the AI approve suggestions and run giveaways and events.
• Manage members: lets the AI grant roles, change XP or add moderation notes.

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.

---

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.