MCP Graph

You are configuring and running an MCP server that executes directed graphs of MCP tool calls. This server lets you declaratively describe tools as graphs, transforming data between steps and routing decisions without writing code. It is useful for composing complex workflows from smaller MCP tools, with full observability of every transformation and decision.

How to use

You use mcpGraph by running it as an MCP server and connecting your MCP client to it. Define your tools and their execution graphs in a YAML configuration, then start the server. Your client can then invoke a tool by name and receive the computed result after the graph finishes.

From your client, list available tools, start a tool with your input data, and handle the final output returned by the graph. Each tool runs through a sequence of nodes that may call other MCP tools, apply data transformations, and make routing decisions. You can trace every step to understand how the input becomes the final result.

How to install

Prerequisites: Node.js is required to run the MCP server tooling. Ensure Node.js is installed on your system before proceeding.

Install the MCP server package globally or add it to your project dependencies.

Install globally with npm:

npm install -g mcpgraph

Or install locally in your project:

npm install mcpgraph

Configuration

To run mcpGraph as an MCP server, you specify a YAML configuration file that defines your server metadata, tools, and the execution graph. You then point your MCP client to this server configuration.

# Example MCP server configuration used by a client
# This snippet shows how to set up a simple mcpGraph server for client usage.
version: "1.0"

server:
  name: "mcpGraph"
  description: "MCP server that executes directed graphs of MCP server calls"

tools:
  - name: "count_files"
    description: "Counts the number of files in a directory"
    inputSchema:
      type: "object"
      properties:
        directory:
          type: "string"
          description: "The directory path to count files in"
      required:
        - directory
    outputSchema:
      type: "object"
      properties:
        count:
          type: "number"
          description: "The number of files in the directory"

servers:
  filesystem:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "./tests/files"

nodes:
  - id: "entry_count_files"
    type: "entry"
    tool: "count_files"
    next: "exit_count_files"
  - id: "exit_count_files"
    type: "exit"
    tool: "count_files"

Examples and notes

You can wire a client to run a graph that lists a directory, transforms the listing into a count, and returns that count as the tool output. The graph can include multiple internal or external MCP server calls, data transformations using JSONata, and routing decisions using JSON Logic.

Available tools

count_files

Counts the number of files in a directory, given a directory path as input.

list_directory

Lists contents of a directory and returns the listing for downstream processing.