home / mcp / cleo mcp server

CLEO MCP Server

Provides an MCP server endpoint that enables portable memory, provenance, and deterministic task orchestration for AI agents.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "kryptobaseddev-cleo": {
      "command": "npx",
      "args": [
        "-y",
        "@cleocode/cleo",
        "--mcp-server"
      ],
      "env": {
        "CLEO_HOME": "/custom/path",
        "CLEO_DEBUG": "1"
      }
    }
  }
}

CLEO MCP Server enables you to run a dedicated MCP endpoint inside the CLEO ecosystem, exposing a portable memory, provenance, and orchestration interface for AI agents. You can connect your MCP client to a local stdio-based CLEO MCP or run the server via a ready-made npm/npx command, enabling automated tool discovery, cross-tool coordination, and deterministic agent execution.

How to use

You interact with the CLEO MCP Server through a client that can call the MCP endpoints exposed by the server. The server provides two primary local, stdio configurations you can run directly from your development environment. You can either launch the server via npx with the MCP flag or run a globally installed CLEO MCP launcher. The server exposes a read/write tool interface, including query-style operations to fetch task state and mutate-style operations to create or modify tasks and related data.

To connect your MCP client, choose one of these approaches:

How to install

Prerequisites you should have before installing the CLEO MCP Server: Node.js and npm, or a compatible runtime that supports npm/npx commands. Ensure you have a modern shell to execute commands.

Option A: Install via npx (recommended for local development) make the MCP server available through your project by using the following command in your project directory.

npx -y @cleocode/cleo --mcp-server

Option B: Install as a global CLI and run the MCP server directly.

npm install -g @cleocode/cleo
cleo-mcp

Starting and connecting to the MCP server

If you used the npx approach, your project now has a local MCP server instance that can be discovered by your CLEO-enabled client. If you installed CLEO globally, you can start the server with the cleo-mcp command.

Configuration and usage notes

The server is configured via MCP configuration blocks in your project or via the global CLEO configuration. The explicit MCP configuration example shows how to declare the server to be launched via npx with the MCP server flag.

What you can do with the MCP server

Read operations allow you to query task state, sessions, and related metadata. Write operations enable you to add, update, or complete tasks, manage sessions, and coordinate orchestration across agents. This setup supports structured memory, provenance, and deterministic agent execution for AI coding workflows.

Security considerations

Operate the MCP server with the principle of least privilege. Do not expose the MCP endpoint publicly without authentication. Use local development configurations when testing, and restrict access in production environments.

Troubleshooting tips

If the MCP server fails to start, verify that the runtime command is available in your PATH and that the necessary npm/npx tooling is installed. Check for conflicting ports or process locks if applicable, and review your installation method (npx vs global) for consistency.

Next steps

Integrate the CLEO MCP Server into your development workflow, start a project, and begin connecting agents to the MCP endpoints for memory and task orchestration. Iterate on your client integrations to leverage the full capabilities of portable memory, provenance, and deterministic execution.

Appendix: MCP server references

The following configurations are supported to run the MCP server locally. You can choose between an inline npx-based start or a global CLI start. Both approaches expose the MCP endpoints used by your client integrations.

Available tools

cleo_query

Read operations tool to query data domains such as tasks and system state.

cleo_mutate

Write operations tool to create, modify, or delete data such as tasks, sessions, or issues.