Turn it on
The Docker Compose installer leaves the endpoint off by default. Add the following to.env in the kodus-installer directory:
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 tohttps://<your-api-host>/mcp on your self-hosted API. The server uses Streamable HTTP.
- Open Organization → CLI keys, generate a key and copy it. Only organization owners can generate keys. See CLI keys.
- Configure your client to send the key in one of these headers when it calls a tool.
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
teamIdargument for another team is rejected, and an omittedteamIdis filled in from the key. - Most tools take an
organizationIdargument. It must be your organization’s ID. Another value is rejected. initialize,tools/listandpingwork without a key. Any other call needs a valid key, and a missing, invalid or revoked key returns401.
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
POSTis 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.