Skip to main content

Adding More MCPs

Kaji comes with a set of pre-configured MCP integrations. If you need to connect additional tools, you can add new MCPs by editing the Kaji configuration file.

What is an MCP server?​

An MCP (Model Context Protocol) server is a small service that gives Kaji the ability to interact with a specific tool or API. Many popular tools have publicly available MCP servers, and you can also build your own.

Resources for finding MCP servers:

How to add a new MCP​

Step 1: Open the Kaji configuration file​

In your Kaji Code-Server session, open the file:

/root/opencode.json

This is the main configuration file for your Kaji environment.

Step 2: Find the mcpServers section​

The file contains a section like this:

{
  "mcpServers": {
    "mattermost": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@some/mattermost-mcp-package"]
    },
    "clickup": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@some/clickup-mcp-package"]
    }
  }
}

Step 3: Add your new MCP​

Add a new entry under mcpServers. The format depends on how the MCP server runs:

NPX-based MCP (most common):

"my-tool": {
  "type": "local",
  "command": "npx",
  "args": ["-y", "@package/name"],
  "env": {
    "API_KEY": "your-api-key-here"
  }
}

Python-based MCP:

"my-tool": {
  "type": "local",
  "command": "uvx",
  "args": ["mcp-package-name"],
  "env": {
    "API_KEY": "your-api-key-here"
  }
}

Remote MCP (SSE):

"my-tool": {
  "type": "sse",
  "url": "https://my-tool-mcp-server.example.com/sse",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

Step 4: Restart Kaji​

After saving the file, restart Kaji in the terminal:

# Exit current kaji session (Ctrl+C or Esc)
kaji

The new MCP will appear in the status panel as Connected if configured correctly.

Storing credentials safely​

API keys and tokens should not be hardcoded in opencode.json if the file is committed to git.

Best practice — use environment variables:

  1. Add your secret to Shakudo's Secrets management (Settings → Secrets)
  2. Reference it in your session environment
  3. In opencode.json, use the environment variable name:
"env": {
  "API_KEY": "${MY_SECRET_ENV_VAR}"
}

Troubleshooting​

MCP shows as "Disconnected":

  • Check the credentials/API key in the config
  • Make sure the package name is correct
  • Check the terminal for error output when Kaji starts

"Command not found" error:

  • For npx MCPs, ensure Node.js is available in the session
  • For uvx MCPs, ensure Python/uv is installed

Need help?​

Contact your Shakudo administrator or reach out on the Shakudo Discord community.