Building mcpGraph Tools with mcpGraphToolkit

This skill teaches you how to use the mcpGraphToolkit MCP server to build, debug, test, run, and manage graph tools in an mcpGraph.

What is an mcpGraph

An mcpGraph is a declarative configuration that defines an MCP (Model Context Protocol) server and its tools, where those tools are implemented as directed graphs. We call those exported tools "graph tools". Each graph tool executes a sequence of nodes that can:

• Call other MCP tools (that are available to the mcpGraph)
• Transform data using JSONata expressions
• Make routing decisions using JSON Logic

When to use mcpGraph:

• You need to orchestrate multiple MCP tool calls in sequence
• You want to transform data between tool calls
• You need conditional routing based on data
• You need to compose complex workflows from simpler MCP tools

Using the mcpGraphToolkit

What you should do:

• ✅ DO use

  listMcpServers

  and

  listMcpServerTools

  to discover available MCP servers and tools
• ✅ DO use

  getMcpServerTool

  to get MCP server tool details and schemas
• ✅ DO use

  addGraphTool

  to add graph tools to the mcpGraph (it handles file operations automatically)
• ✅ DO use

  updateGraphTool

  and

  deleteGraphTool

  to manage graph tools
• ✅ DO use

  runGraphTool

  to run a graph tool or to test a graph tool before adding it
• ✅ DO use

  listGraphTools

  and

  getGraphTool

  to discover and examine existing graph tools, especially when considering creating a new graph tool

⚠️ CRITICAL: Use Only the Provided Tools to interact with an mcpGraph

DO NOT create, edit, or read configuration files directly. mcpGraphToolkit uses configuration files internally (such as graph configuration files and MCP server configuration files), but you should never attempt to create, edit, or read directly from these files. The toolkit tools provide all the functionality you need to understand and manipulate the state of the mcpGraph.

Terminology: MCP Servers/Tools vs Graph Tools

Important: Understanding the distinction between MCP servers/tools and graph tools is critical.

MCP Servers and Tools (Available to the Graph)

• MCP Servers: External MCP servers that are available to the graph (discovered via

  listMcpServers

  )
• MCP Tools: Tools provided by those MCP servers (discovered via

  listMcpServerTools

  and

  getMcpServerTool

  )
• These are the building blocks that graph tools can use
• Graph tools can only use MCP servers and tools that are available to the graph (as determined by the toolkit's discovery APIs)
• Use

  listMcpServers

  and

  listMcpServerTools

  to see what's available before building graph tools

Graph Tools (What You Create and Manage)

• Graph Tools: Tools you create, manage, and run using mcpGraphToolkit
• These are composed from MCP tools, transform nodes, and switch nodes
• Once created, graph tools can be called like MCP tools using

  runGraphTool

• Graph tools are stored in the graph configuration and can be discovered via

  listGraphTools

Key Points:

• Graph tools orchestrate MCP tools - they call MCP tools in sequence, transform data, and make routing decisions
• Graph tools can only use MCP servers/tools that are available to the graph (check with

  listMcpServers

  first)
• Always check if an existing graph tool already serves your purpose before creating a new one (use

  listGraphTools

  and

  getGraphTool

  )
• Graph tools you create become available as callable tools, via

  runGraphTool

Graph Tool Structure

A graph tool is a

ToolDefinition

with this structure:

{
  "name": "tool_name",
  "description": "Tool description",
  "inputSchema": {
    "type": "object",
    "properties": { ... },
    "required": [ ... ]
  },
  "outputSchema": {
    "type": "object",
    "properties": { ... }
  },
  "nodes": [
    { "id": "entry", "type": "entry", "next": "..." },  // REQUIRED
    // ... worker nodes (mcp, transform, switch) ...
    { "id": "exit", "type": "exit" }  // REQUIRED
  ]
}

Required Components:

• name

  : Tool identifier (string)

• description

  : Tool description (string)

• inputSchema

  : JSON Schema for tool inputs (REQUIRED - must be object type)

• outputSchema

  : JSON Schema for tool outputs (REQUIRED - must be object type)

• nodes

  : Array of nodes (MUST include exactly one entry node and exactly one exit node)

Node Types and Required Fields:

Node Types

Entry Node

Entry point that receives tool arguments. Required in every graph tool.

• id

  : Node identifier (typically

  "entry"

  )

• type

  :

  "entry"

• next

  : ID of the first worker node

Output: Tool input arguments (passed through as-is)

{
  "id": "entry",
  "type": "entry",
  "next": "list_directory_node"
}

MCP Node

Calls an MCP tool on a server available to the graph. Type is exactly

"mcp"

(NOT "mcp-tool", "mcp-tool-call", etc).

• id

  : Node identifier

• type

  :

  "mcp"

• server

  : MCP server name (must be available via

  listMcpServers

  )

• tool

  : Tool name (must be available via

  listMcpServerTools

  )

• args

  : Arguments (values starting with

  $

  are evaluated as JSONata)

• next

  : ID of the next node

Output: MCP tool's response (parsed from content)

{
  "id": "list_directory_node",
  "type": "mcp",
  "server": "filesystem",
  "tool": "list_directory",
  "args": {
    "path": { "expr": "$.entry.directory" }
  },
  "next": "count_files_node"
}

Important: Only use servers/tools discovered via

listMcpServers

and

listMcpServerTools

.

Transform Node

Applies JSONata expressions to transform data.

• id

  : Node identifier

• type

  :

  "transform"

• transform.expr

  : JSONata expression (string)

• next

  : ID of the next node

Output: Result of evaluating the JSONata expression

{
  "id": "count_files_node",
  "type": "transform",
  "transform": {
    "expr": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }"
  },
  "next": "exit"
}

Switch Node

Uses JSON Logic to conditionally route to different nodes.

• id

  : Node identifier

• type

  :

  "switch"

• conditions

  : Array of

  { rule, next }

  objects

• next

  : Default next node (used if no conditions match)

Output: Node ID of the routed-to node (string)

{
  "id": "switch_node",
  "type": "switch",
  "conditions": [
    {
      "rule": {
        ">": [{ "var": "entry.value" }, 10]
      },
      "next": "high_path"
    },
    {
      "rule": {
        ">": [{ "var": "entry.value" }, 0]
      },
      "next": "low_path"
    }
  ],
  "next": "zero_path"
}

Note:

var

operations in JSON Logic rules are evaluated using JSONata (see Expressions section).

Exit Node

Exit point that returns the final result. Required in every graph tool.

• id

  : Node identifier (typically

  "exit"

  )

• type

  :

  "exit"

• No

  next

  field - execution ends here

Output: Output from the previous node in execution history

{
  "id": "exit",
  "type": "exit"
}

Critical Rules:

• Every graph tool MUST have exactly one entry node (typically

  id: "entry"

  )
• Every graph tool MUST have exactly one exit node (typically

  id: "exit"

  )
• Entry node receives tool arguments and must have a

  next

  field pointing to the first worker node
• Exit node returns the final result and has NO

  next

  field (execution ends here)
• MCP node type is

  "mcp"

  (NOT "mcp-tool", "mcp-tool-call", or any other variant)
• All tools MUST include both

  inputSchema

  and

  outputSchema

  (both must be object type)
• Exit node returns the output from the previous node in the execution history (no special output mechanism needed)

Example Structure:

{
  "name": "count_files",
  "description": "Counts files in a directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "directory": { "type": "string" }
    },
    "required": ["directory"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "count": { "type": "number" }
    }
  },
  "nodes": [
    {
      "id": "entry",
      "type": "entry",
      "next": "list_directory_node"
    },
    {
      "id": "list_directory_node",
      "type": "mcp",
      "server": "filesystem",
      "tool": "list_directory",
      "args": {
        "path": { "expr": "$.entry.directory" }
      },
      "next": "count_files_node"
    },
    {
      "id": "count_files_node",
      "type": "transform",
      "transform": {
        "expr": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }"
      },
      "next": "exit"
    },
    {
      "id": "exit",
      "type": "exit"
    }
  ]
}

mcpGraphToolkit Tools

mcpGraphToolkit provides 12 tools organized into categories:

Graph Discovery Tools

• getGraphServer

  : Get full details of the mcpGraph server metadata (name, version, title, instructions)

• listGraphTools

  : List all graph tools in the mcpGraph (name and description)
  • Always check this first before creating a new graph tool - an existing graph tool may already serve your purpose

• getGraphTool

  : Get full detail of a graph tool from the mcpGraph (including complete node definitions)
  • Use this to understand existing graph tools before creating new ones

MCP Server Discovery Tools

• listMcpServers

  : List all MCP servers available to the graph (name, title, instructions, version)
  • These are the MCP servers that graph tools can use
  • Graph tools can only use MCP servers listed here

• listMcpServerTools

  : List tools from MCP servers available to the graph (name/description only), optionally filtered by MCP server name
  • These are the MCP tools that graph tools can call

• getMcpServerTool

  : Get full MCP server tool details (including input and output schemas)
  • Use this to understand how to call MCP tools from your graph tools

Graph Tool Management Tools

• addGraphTool

  : Add a new tool to the mcpGraph

• updateGraphTool

  : Update an existing tool in the mcpGraph

• deleteGraphTool

  : Delete a tool from the mcpGraph

Tool Execution Tools

• runGraphTool

  : Run an exported tool from the mcpGraph. Can specify existing tool name or run a tool definition supplied in payload. Supports optional logging collection.

Expression Testing Tools

• testJSONata

  : Test a JSONata expression with context

• testJSONLogic

  : Test a JSON Logic expression with context

• testMcpTool

  : Test an MCP tool call directly to understand its output structure and behavior

Graph Structure and Flow

A graph is a directed sequence of nodes that execute in order. Execution flow:

1. Starts at the entry node (receives tool arguments)
2. Executes nodes sequentially based on

   next

   fields
3. switch nodes can conditionally route to different nodes
4. Continues until the exit node is reached
5. Exit node returns the final result

Node Connections

Nodes are connected using the

next

field, which specifies the ID of the next node to execute:

{
  "id": "count_files_node",
  "type": "transform",
  "transform": {
    "expr": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }"
    },
    "next": "exit"
}

Switch nodes use

conditions

with

next

fields (each condition specifies its own

next

node), plus a top-level

next

field as the default:

{
  "id": "switch_node",
  "type": "switch",
  "conditions": [
    {
      "rule": { ">": [{ "var": "entry.value" }, 10] },
      "next": "high_path"
    }
  ],
  "next": "default_path"
}

Execution Context

During execution, each node's output is stored in the execution context. You can access node outputs using JSONata expressions:

• $.node_id

  - Accesses the latest output of a node with ID

  node_id

• $.entry.paramName

  - Accesses a parameter from the entry node

The context is a flat structure:

{ "node_id": output, ... }

Expressions

mcpGraph uses two expression languages: JSONata for data transformation and JSON Logic for conditional routing.

JSONata

JSONata is used in three places:

1. Transform node expressions (

   transform.expr

   ) - Transform data between nodes
2. MCP tool node arguments - Any argument value starting with

   $

   is evaluated as JSONata
3. JSON Logic

   var

   operations - Access context data in switch node conditions

Basic Syntax:

• Property access:

  $.node_id.property

  or

  $.entry.paramName

• Object construction:

  { "key": value }

• Functions:

  $count(array)

  ,

  $split(string, delimiter)

  , etc.
• Conditional:

  condition ? trueValue : falseValue

History Functions (for loops):

• $executionCount(nodeName)

  - Count executions of a node

• $nodeExecution(nodeName, index)

  - Get specific execution (0 = first, -1 = last)

• $nodeExecutions(nodeName)

  - Get all executions as array

• $previousNode()

  - Get previous node's output

Examples:

Transform node:

{
  "transform": {
    "expr": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }"
  }
}

MCP node args:

{
  "args": {
    "path": { "expr": "$.entry.directory" }
  }
}

In JSON Logic var:

{
  "var": "$.increment_node.counter"
}

Testing: Use

testJSONata

tool to validate expressions before adding to nodes.

JSON Logic

JSON Logic is used in switch node conditions for conditional routing.

Basic Syntax:

• Comparison:

  { ">": [a, b] }

  ,

  { "<": [a, b] }

  ,

  { "==": [a, b] }

• Logical:

  { "and": [rule1, rule2] }

  ,

  { "or": [rule1, rule2] }

  ,

  { "!": rule }

• Variable access:

  { "var": "path" }

  or

  { "var": "$.node_id.property" }

Important:

var

operations are evaluated using JSONata, so you can use full JSONata expressions including history functions.

Examples:

Simple comparison:

{
  "rule": {
    ">": [{ "var": "entry.value" }, 10]
  }
}

Complex condition:

{
  "rule": {
    "and": [
      { ">": [{ "var": "entry.price" }, 100] },
      { "==": [{ "var": "entry.status" }, "active"] }
    ]
  }
}

With JSONata:

{
  "rule": {
    "<": [
      { "var": "$.increment_node.counter" },
      { "var": "$.increment_node.target" }
    ]
  }
}

Testing: Use

testJSONLogic

tool to validate conditions before adding to switch nodes.

Understanding MCP Tool Outputs

When an MCP tool executes in a graph node, its output is stored in the execution context using the node ID. However, the structure of that output varies by tool, which can cause confusion when building graph tools.

Output Structure Patterns

Different MCP tools return data in different formats:

1. Direct/Plain Output - Tool returns data directly (string, number, object, etc.)

   // Tool output stored as:
   { "fetch_url": "Content here..." }
   
   // Access in JSONata:
   $.fetch_url
   

2. Wrapped Output - Tool returns an object with nested properties

   // Tool output stored as:
   { "get_info": {"content": "File info here..."} }
   
   // Access in JSONata:
   $.get_info.content
   

How to Determine Output Structure

1. Use

   getMcpServerTool

   - Check the tool's

   outputSchema

   to understand the expected structure
2. Use

   testMcpTool

   - Test the tool directly to see its actual output (recommended)
3. Use

   runGraphTool

   with logging - Run a minimal graph with just entry → mcp → exit and check

   executionHistory

Testing MCP Tools with

testMcpTool

The

testMcpTool

tool allows you to test MCP tool calls directly without creating a full graph tool. This is the fastest way to understand how a tool behaves and what output structure it returns.

Basic Usage:

{
  "tool": "testMcpTool",
  "arguments": {
    "server": "fetch",
    "tool": "fetch",
    "args": {
      "url": "https://example.com",
      "raw": true
    }
  }
}

Response:

{
  "output": "Content type text/plain cannot be simplified...",
  "executionTime": 267
}

With JSONata Expression Evaluation:

{
  "tool": "testMcpTool",
  "arguments": {
    "server": "filesystem",
    "tool": "write_file",
    "args": {
      "path": { "expr": "$.entry.filename" },
      "content": { "expr": "$.fetch_result" }
    },
    "context": {
      "entry": {"filename": "test.txt"},
      "fetch_result": "Some content here"
    }
  }
}

Response:

{
  "evaluatedArgs": {
    "path": "test.txt",
    "content": "Some content here"
  },
  "output": {"content": "Successfully wrote to test.txt"},
  "executionTime": 8
}

Key Points:

• output

  matches what would be available in a graph node's execution context
• The output structure depends on the tool's response format (may be an object, string, or other type)
• Use

  getMcpServerTool

  to understand the tool's

  outputSchema

  and expected output structure

• evaluatedArgs

  is included when JSONata expressions are used in

  args

  and

  context

  is provided

• executionTime

  shows how long the tool call took in milliseconds

Why This Matters: Understanding the exact output structure is critical when building transform nodes or switch conditions that reference MCP tool outputs. Using

testMcpTool

before building your graph tool saves significant debugging time.

Building Tools with mcpGraphToolkit

Workflow

IMPORTANT: Follow this workflow exactly. Do not skip steps or try to create files manually.

0. Check for Existing Graph Tools

   • ALWAYS START HERE: Use

     listGraphTools

     to see if a graph tool already exists for your purpose
   • Use

     getGraphTool

     to examine existing graph tools before creating new ones
   • Only create a new graph tool if no existing tool serves your purpose

1. Discover Available MCP Servers and Tools

   • MUST USE

     listMcpServers

     to see MCP servers available to the graph (graph tools can only use these servers)
   • MUST USE

     listMcpServerTools

     to see MCP tools available on a server (graph tools can only call these tools)
   • MUST USE

     getMcpServerTool

     to get full tool details (input/output schemas)
   • RECOMMENDED: Use

     testMcpTool

     to understand tool behavior and output structure before using it in a graph
   • Remember: Graph tools can only use MCP servers and tools that are available to the graph (as shown by these discovery tools)
   • DO NOT attempt to read configuration files to discover MCP servers - use the toolkit discovery tools instead

2. Test Components

   • Use

     testMcpTool

     to test MCP tool calls and understand their output structure
   • Use

     testJSONata

     to test transform expressions (use actual MCP tool outputs from

     testMcpTool

     as context)
   • Use

     testJSONLogic

     to test switch conditions
   • Iterate until all components work correctly

3. Build Tool Definition

   • Construct nodes using MCP servers and tools that are available to the graph (from step 1)
   • Only reference MCP servers and tools that were discovered via

     listMcpServers

     and

     listMcpServerTools

   • Use tested expressions in transform and switch nodes
   • Define entry and exit nodes
   • Specify input and output schemas

4. Test Tool Definition Before Adding

   • Use

     runGraphTool

     with

     toolDefinition

     to test the tool inline (testing from source)
   • Optionally enable

     logging: true

     to see execution details
   • Verify the tool works correctly
   • IMPORTANT: Use the exact same tool definition in Step 5

5. Add Tool to Graph

   • MUST USE

     addGraphTool

     to add the tested tool to the graph
   • CRITICAL: Use the exact same tool definition from Step 4
   • DO NOT create or edit configuration files directly
   • The tool is saved automatically by the toolkit (all file operations are handled internally)

6. Verify Tool in Graph (Recommended)

   • Use

     runGraphTool

     with

     toolName

     (the tool's name) to test it from the graph
   • This verifies the tool was saved correctly and works when called from the graph
   • Compare results with Step 4 to ensure consistency

7. Update or Delete Tools

   • MUST USE

     updateGraphTool

     to modify existing tools (do NOT edit configuration files directly)
   • MUST USE

     deleteGraphTool

     to remove tools (do NOT edit configuration files directly)
   • Changes are saved automatically by the toolkit (all file operations are handled internally)

Debugging Strategy

When building or debugging graph tools, follow this systematic approach:

1. Test MCP Tools Individually

   • Use

     testMcpTool

     to call the MCP tool directly and see its output structure
   • This helps you understand what data will be available in the execution context
   • Don't guess at output structure - test it first

2. Test Expressions with Realistic Context

   • Use outputs from

     testMcpTool

     as context for

     testJSONata

     expressions
   • Use actual data structures, not guessed structures
   • This prevents errors like trying to access

     $.fetch_url.content

     when the tool returns a plain string

3. Build Incrementally

   • Start with entry → first_mcp → exit
   • Add one transform or switch node at a time
   • Test after each addition using

     runGraphTool

     with

     logging: true

4. Use Debugging Tools

   • testMcpTool

     - Verify MCP tool calls work and understand output structure

   • testJSONata

     - Validate transform expressions before using them

   • testJSONLogic

     - Validate switch conditions before using them

   • runGraphTool

     with

     logging: true

     - See all execution steps and node outputs

   • executionHistory

     - Inspect actual node outputs when debugging

Example: Debugging a Failed Transform

Error:

"content": "expected string, received undefined"

Steps:

1. Use

   testMcpTool

   to see what the MCP tool actually returns
2. Use

   testJSONata

   with the actual output structure as context:

   {
     "tool": "testJSONata",
     "arguments": {
       "expression": "$.fetch_url.content",
       "context": {
         "fetch_url": "actual output from testMcpTool"
       }
     }
   }
   

3. Adjust the expression based on the actual structure (e.g., use

   $.fetch_url

   if it's a plain string)

Example: Building a File Counter Tool

Step 0: Check for Existing Tools

{
  "tool": "listGraphTools",
  "arguments": {}
}

Step 1: Discover Available MCP Servers and Tools

{
  "tool": "listMcpServers",
  "arguments": {}
}

{
  "tool": "listMcpServerTools",
  "arguments": {
    "serverName": "filesystem"
  }
}

{
  "tool": "getMcpServerTool",
  "arguments": {
    "serverName": "filesystem",
    "toolName": "list_directory"
  }
}

Step 2: Test MCP Tool and Understand Output Structure

{
  "tool": "testMcpTool",
  "arguments": {
    "server": "filesystem",
    "tool": "list_directory",
    "args": {
      "path": "/path/to/test/directory"
    }
  }
}

This returns the actual output structure. For example, if it returns:

{
  "output": {
    "content": "[FILE] file1.txt\n[FILE] file2.txt\n[FILE] file3.txt\n"
  },
  "executionTime": 15
}

Now you know the output structure and can use it in expressions.

Step 3: Test Expressions with Actual Output Structure

{
  "tool": "testJSONata",
  "arguments": {
    "expression": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }",
    "context": {
      "list_directory_node": {
        "content": "[FILE] file1.txt\n[FILE] file2.txt\n[FILE] file3.txt\n"
      }
    }
  }
}

Step 4: Test Complete Tool Definition (from source)

Test your tool definition using

runGraphTool

with

toolDefinition

:

{
  "tool": "runGraphTool",
  "arguments": {
    "toolDefinition": {
      "name": "count_files",
      "description": "Counts files in a directory",
      "inputSchema": {
        "type": "object",
        "properties": { "directory": { "type": "string" } },
        "required": ["directory"]
      },
      "outputSchema": {
        "type": "object",
        "properties": { "count": { "type": "number" } }
      },
      "nodes": [
        {
          "id": "entry",
          "type": "entry",
          "next": "list_directory_node"
        },
        {
          "id": "list_directory_node",
          "type": "mcp",
          "server": "filesystem",
          "tool": "list_directory",
          "args": {
            "path": { "expr": "$.entry.directory" }
          },
          "next": "count_files_node"
        },
        {
          "id": "count_files_node",
          "type": "transform",
          "transform": {
            "expr": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }"
          },
          "next": "exit"
        },
        {
          "id": "exit",
          "type": "exit"
        }
      ]
    },
    "arguments": {
      "directory": "/path/to/directory"
    },
    "logging": true
  }
}

Step 5: Add Tool to Graph

Once validated, use

addGraphTool

with the exact same tool definition from Step 4:

{
  "tool": "addGraphTool",
  "arguments": {
    "tool": {
      /* SAME tool definition from Step 4 */
      "name": "count_files",
      "description": "Counts files in a directory",
      "inputSchema": {
        "type": "object",
        "properties": {
          "directory": {
            "type": "string"
          }
        },
        "required": ["directory"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number"
          }
        }
      },
      "nodes": [
        {
          "id": "entry",
          "type": "entry",
          "next": "list_directory_node"
        },
        {
          "id": "list_directory_node",
          "type": "mcp",
          "server": "filesystem",
          "tool": "list_directory",
          "args": {
            "path": { "expr": "$.entry.directory" }
          },
          "next": "count_files_node"
        },
        {
          "id": "count_files_node",
          "type": "transform",
          "transform": {
            "expr": "{ \"count\": $count($split($.list_directory_node.content, \"\\n\")) }"
          },
          "next": "exit"
        },
        {
          "id": "exit",
          "type": "exit"
        }
      ]
    }
  }
}

Step 6: Verify Tool in Graph (Recommended)

Test the tool again, but now using the tool name (running from the graph, not from source):

{
  "tool": "runGraphTool",
  "arguments": {
    "toolName": "count_files",
    "arguments": {
      "directory": "/path/to/directory"
    },
    "logging": true
  }
}

This verifies:

• The tool was saved correctly to the graph
• The tool works when called from the graph (not just from source)
• Results match Step 4, confirming consistency

Resources

• JSONata Documentation: https://jsonata.org/
• JSON Logic Documentation: https://jsonlogic.com/
• MCP Specification: https://modelcontextprotocol.io/