Jotsu

General-purpose library for implementing the Model Context Protocol (MCP) and creating workflows that use MCP tools, resources and prompts.

Quickstart

Install the package, including the CLI.

pip install jotsu-mcp[cli]

Create an empty workflow.

jotsu-mcp workflow init

The initialization command creates a workflow file 'workflow.json' in the current directory.

Run it:

jotsu-mcp workflow run ./workflow.json

The output consists of three messages: the workflow start, the single node’s message, and the workflow end. The final result appears in the result field of the workflow-end node, which in this example is an empty object.

Hello MCP

The workflow can call a tool from an MCP server. This allows you to use MCP with models that don't yet support it (really any model other than Claude).

Add the following server entry:

{
    "id": "hello",
    "name": "Hello World",
    "url": "https://hello.mcp.jotsu.com/mcp/"
}

NOTE: IDs may only contain lowercase letters, numbers, :, _, or -. NOTE: don't forget the path /mcp/ on the URL.

This server is a publicly available MCP server (with no authentication) that has a couple of resources and a tool. (The code is available here).

Next add a node for a server tool.

[
    {"id":  "greet", "type":  "tool", "name": "greet", "server_id":  "hello"}
]

Add some initial data that the 'greet' tool needs:

{"name": "World"}

By default, the workflow starts with the first node, but you can also explicitly set the start node:

"start_node_id": "greet"

Finally, add a 'generic' node at the end. Generic nodes are application-specific - meaning the workflow only handles them by yielding the data - and are generally used for output and/or debugging.
The type can be any string not already used by the workflow. In this case, 'output'.

{
    "id": "quickstart",
    "name": "quickstart",
    "description": "Simple workflow to interact with the 'hello' MCP server",
    "nodes": [
        {"id":  "greet", "type":  "tool", "name": "greet", "server_id":  "hello", "edges":  ["output"]},
        {"id":  "output", "type":  "output", "name": "The result"}
    ],
    "servers": [
        {
            "id": "hello",
            "name": "Hello World",
            "url": "https://hello.mcp.jotsu.com/mcp/"
        }
    ],
    "data": {"name":  "World"},
    "metadata": null
}

Running this workflow again generates a lot more data, but specifically there is a line similar to:

{
  "action": "default",
  "timestamp": 132462.392532502,
  "id": "01k3h80zcaz050eg7080r3fnv7",
  "run_id": "01k3h80t6psmg0s5swsg4yke95",
  "node": {
    "id": "output",
    "name": "The result",
    "type": "output"
  },
  "data": {
    "name": "World",
    "greet": "Hello, World!"
  }
}

The data from this node acts as the 'result' of the workflow. Since workflows can have many branches there is one 'result', instead there could be many such lines depending upon the actions the workflow took.

Development

uv venv
uv pip install '.[dev,cli,anthropic,openai,cloudflare,cryptography]'