Plugin and MCP server integration
How to connect your own MCP server to Keural and create a plugin package for the desktop app.
Keural plugins are MCP (Model Context Protocol) servers. This document specifies how to connect your own MCP server to Keural, or how to create a plugin package for the desktop app.
Transport methods
| Platform | Transport | Use |
|---|---|---|
| Web and mobile | HTTP (Streamable HTTP) · SSE | Remote MCP servers reachable from the internet |
| Desktop app | STDIO · HTTP | Servers that run on this computer, and HTTP servers on your internal network |
- In web conversations, only remote HTTP and SSE servers are used. STDIO servers run in the desktop app.
- If a server address ends with
/mcp, it is usually a Streamable HTTP server, so choose HTTP as the transport method. - HTTP in the desktop app is for internal network addresses. Register public internet addresses with HTTP on the web.
Input fields for custom MCP
The input fields under Settings → Plugins → ＋ Add custom MCP are as follows.
| Field | Content |
|---|---|
| Name | Required |
| Description | Optional |
| Transport | See the table above |
| Category | Classification in the list |
| Server URL | Required for HTTP or SSE. Example: https://example.com/mcp |
| Run command | Required for STDIO. Example: npx |
| Arguments | STDIO arguments (JSON array). Example: ["-y", "@scope/server"] |
| Use this plugin for web search | When on, this plugin is used instead of web search. |
| Authentication | None · API key |
| Header name · API key value | For API key. Example: header name Authorization, value Bearer … |
When you select API key, Keural attaches the <header name>: <value> header to every request.
OAuth authentication servers
A plugin that an organization admin registered with OAuth is connected when the user selects Connect and signs in.
| Item | Value |
|---|---|
| Server discovery | /.well-known/oauth-protected-resource (with path → root), then /.well-known/oauth-authorization-server |
| Client registration | Dynamic Client Registration (DCR) |
| Redirect URI | https://api.keural.ai/api/user-connectors/oauth/callback |
| Request header | Authorization: Bearer <access token> |
The sign-in window opens as a pop-up, and the plugin list is refreshed when sign-in finishes.
Tool permissions
Set how each plugin tool runs.
| Permission | Behavior |
|---|---|
| Always allow | Runs without confirmation. |
| Ask first | Shows an approval card before running. The card also shows the tool arguments. |
| Block | The agent does not use this tool. |
Desktop plugin package
The desktop app installs plugins with Plugin ZIP file… or Plugin folder…. The package requires the plugin.json manifest.
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"description": "Query internal systems",
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": { "API_BASE": "https://intranet.example.com" }
}
}
}| Field | Required | Content |
|---|---|---|
id | Yes | Lowercase English letters, digits, and hyphens |
name | No | Display name. If missing, id is used. |
version | No | Default 1.0.0 |
description | No | Description |
minAppVersion | No | Minimum app version required |
mcpServers | No | MCP server definitions. Each server has command, args, and env. |
requests | No | Requested permissions (capabilities, commands, connectors, secrets, permissions). Array of strings |
To install a STDIO plugin registered on the web, select Install on this PC in the desktop app. After installation, enter the authentication token and environment variables yourself.