Skip to content
Cyoda Documentation
Settings

Python client template and MCP

Repository: github.com/Cyoda/mcp-cyoda-quart-app · Apache-2.0

The repository contains two things:

  • an opinionated Python application template for Cyoda compute nodes, built on the asynchronous Quart framework — fork it to start a project
  • mcp-cyoda, an MCP server that lets AI assistants read and write entities, search, send edge messages, and manage workflows on a Cyoda instance

Both need a Cyoda instance and an M2M client (client_id and secret). On cyoda-go, see cyoda help auth clients.

Application template

Section titled “Application template”

The template is optional. Compute nodes can be written in any language that speaks the compute-node protocol, and AI coding agents build them directly from cyoda help, the API reference, and Cyoda Skills.

The template manages entities, runs their workflows, and connects to Cyoda over gRPC to execute processors and criteria. It also exposes REST endpoints for entity and workflow operations.

Path Contents
application/ Application code: entity/, routes/, processor/
common/ Shared infrastructure: auth, config, gRPC client, repository, service interfaces
example_application/ Reference implementation
cyoda_mcp/ The MCP server
tests/ Test suite

Run it

Section titled “Run it”
Terminal window
git clone https://github.com/Cyoda/mcp-cyoda-quart-app.git
cd mcp-cyoda-quart-app
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt


export CYODA_CLIENT_ID=<client-id>
export CYODA_CLIENT_SECRET=<client-secret>
export CYODA_HOST=<cyoda-host>


python -m application.app

CYODA_HOST is the host name only, without a scheme.

MCP server

Section titled “MCP server”

mcp-cyoda is published on PyPI. Run it without installing:

Terminal window
pipx run mcp-cyoda

or install it once:

Terminal window
pipx install mcp-cyoda
mcp-cyoda                                  # stdio (default)
mcp-cyoda --transport http --port 9000     # HTTP

The transport is stdio, http, or sse, set with --transport or MCP_TRANSPORT. The server reads the same CYODA_* variables as the template.

Register it with an MCP client (Claude Code, Claude Desktop, Cursor, and others):

{
  "mcpServers": {
    "cyoda": {
      "command": "mcp-cyoda",
      "env": {
        "CYODA_CLIENT_ID": "<client-id>",
        "CYODA_CLIENT_SECRET": "<client-secret>",
        "CYODA_HOST": "<cyoda-host>"
      }
    }
  }
}

Capabilities

Section titled “Capabilities”
Area Operations
Entities Create, read, update, delete, list by model
Search Field-based and condition-based search
Edge messages Send and retrieve
Workflows Export, import, copy between entity models
Section titled “Related”