Skip to main content
The MCP server is available exclusively on self-hosted Kodus. It exposes a workspace’s repositories, pull requests, Kody Issues, Kody Rules and memories as tools for an MCP client. To connect external tools to Kody through Plugins, set up MCP Manager.

Turn it on

The Docker Compose installer leaves the endpoint off by default. Add the following to .env in the kodus-installer directory:
Run docker compose up -d --no-deps api from that directory to apply the new environment. The Helm chart enables the endpoint by default. Set global.config.API_MCP_SERVER_ENABLED to "false" in your values file and run helm upgrade if you want to disable it. While it is off, the API does not serve /mcp. The route is POST /mcp on the API host, so a reverse proxy must forward it. See Reverse Proxy.

Connect a client

Connect to https://<your-api-host>/mcp on your self-hosted API. The server uses Streamable HTTP.
  1. Open Organization → CLI keys, generate a key and copy it. Only organization owners can generate keys. See CLI keys.
  2. Configure your client to send the key in one of these headers when it calls a tool.
To check the connection, replace kodus-api.example.com with your API hostname and list the tools. This discovery request runs without a key.
  • A key belongs to one team. A teamId argument for another team is rejected, and an omitted teamId is filled in from the key.
  • Most tools take an organizationId argument. It must be your organization’s ID. Another value is rejected.
  • initialize, tools/list and ping work without a key. Any other call needs a valid key, and a missing, invalid or revoked key returns 401.

Tools

Repositories and pull requests

Kody Issues

Kody Rules and memories

Managing rules and memories

KODUS_CREATE_KODY_RULE, KODUS_UPDATE_KODY_RULE, KODUS_DELETE_KODY_RULE and KODUS_CREATE_MEMORY need the kodyRules:manage capability on the key. In Organization → CLI keys, click Configure on the key and turn on Allow Kody Rules management via CLI. Without it these tools return an error result (isError: true) saying the key does not have permission to manage Kody Rules. The other tools need no capability.
  • A rule created through the server shows the MCP/Agent origin and waits in Pending review until someone approves it.
  • A memory waits there only when Kody knowledge approval is on.
  • With a centralized config enabled, creating, changing or deleting a rule or memory opens a pull request on the config repository instead.

Limits

  • Only POST is supported.
  • Stateless. The server keeps no session between requests and returns no Mcp-Session-Id.
  • It sends nothing to the client outside the response to a POST.