Run Local and Remote Tools via MCP in Jinba Flow

Use MCP_LOCAL_RUN and MCP_REMOTE_RUN with the Model Context Protocol to integrate local and remote tools into Jinba Flow workflows for tool execution.

MCP (Model Context Protocol) Tools enable integration with MCP servers for extended functionality. These tools allow you to connect to both local (stdio) and remote (Streamable HTTP) MCP servers, fetch the list of tools the server exposes, pick one, and execute it with your inputs. The call itself runs in the Python sandbox with the MCP Python SDK.

Tools

MCP_LOCAL_RUN

• Starts a local MCP server as a subprocess (stdio transport) and calls one of its tools
• Single mcp input (configured in the step editor) with command (default npx), args (default ["-y"]), optional env, the fetched tools list, the selectedTool ID, and toolInputs for that tool
• command, selectedTool, and toolInputs are required at run time; otherwise the step fails with Missing required fields: command, selectedTool, or toolInputs

MCP_REMOTE_RUN

• Connects to a remote MCP server over Streamable HTTP and calls one of its tools
• Single mcp input with server_url, optional headers (for example an Authorization header), the fetched tools list, the selectedTool ID, and toolInputs
• server_url, selectedTool, and toolInputs are required at run time; otherwise the step fails with Missing required fields: server_url, selectedTool, or toolInputs

Both tools have no configuration fields. The setup is interactive: open the step in the editor, fetch the server’s tools, select one, and fill in its inputs. The selected tool and its inputs are then saved on the step.

Authentication

MCP tools have no config of their own. Pass credentials through the mcp input: env for a local server (for example an API key the server reads from its environment) or headers for a remote server. Store secrets as Flow secrets and reference them with {{secrets.NAME}}.

Call a tool on a local MCP server

Replace your-mcp-server-package, read_document, and the toolInputs with the package, tool name, and input schema of the MCP server you fetched in the step editor.

- id: read_document
  name: read_document
  tool: MCP_LOCAL_RUN
  input:
    - name: mcp
      value:
        command: npx
        args: ["-y", "your-mcp-server-package"]
        env:
          EXAMPLE_API_KEY: "{{secrets.EXAMPLE_API_KEY}}"
        selectedTool: read_document
        toolInputs:
          path: "/data/report.txt"

- id: summarize_document
  name: summarize_document
  tool: OPENAI_INVOKE
  needs: [read_document]
  input:
    - name: prompt
      value: |
        Summarize the following document:
        {{steps.read_document.result}}

Call a tool on a remote MCP server

- id: input_data
  name: input_data
  tool: INPUT_FILE
  input:
    - name: description
      value: "Data file to analyze"

- id: execute_remote_analysis
  name: execute_remote_analysis
  tool: MCP_REMOTE_RUN
  needs: [input_data]
  input:
    - name: mcp
      value:
        server_url: "https://mcp-server.example.com/mcp"
        headers:
          Authorization: "Bearer {{secrets.MCP_AUTH_TOKEN}}"
        selectedTool: data_analyzer
        toolInputs:
          data_source: "{{steps.input_data.result}}"
          analysis_type: "statistical_summary"

- id: save_analysis_results
  name: save_analysis_results
  tool: OUTPUT_FILE
  needs: [execute_remote_analysis]
  input:
    - name: content
      value: "{{steps.execute_remote_analysis.result}}"
    - name: filename
      value: "mcp_analysis_results.json"
    - name: fileType
      value: "json"

Read the result

result holds what the MCP tool returned:

• If the tool returns structuredContent, result is that object.
• Otherwise, result is the text of the tool’s content blocks: a single string when there is one block, or an array of strings when there are several. If that text is JSON, it is parsed, so result can be an object or array.
• If the tool returns no content, result is null.

Inspect the actual value of steps.<id>.result for your server before referencing nested fields in later steps.

Error Handling

• Missing fields: MissingFieldsError when command / server_url, selectedTool, or toolInputs are not set — open the step, fetch tools, and complete the setup.
• Server or tool errors: an exception raised while connecting to the server or calling the tool fails the step with An error occurred while the tool was executing: ... in the step error (MCP_REMOTE_RUN reports An error occurred while the tool was executing. without the detail).

Use Cases

• Data Processing: Advanced data transformation and analysis
• Document Processing: Complex document parsing and extraction
• AI/ML Integration: Machine learning model execution
• Custom Workflows: Domain-specific business logic execution
• External API Integration: Wrapper for external services
• Batch Processing: Large-scale data processing operations
• Specialized Tools: Industry-specific processing tools
• Research Tools: Academic and scientific computing tools

Best Practices

Performance Optimization

• Use local servers for frequent operations
• Use remote servers for compute-intensive tasks
• Keep toolInputs small; pass file URLs rather than file contents where the server supports it

Security Considerations

• In an organization with an egress policy, a local MCP server runs in the same kind of locked-down sandbox as Python code: no sudo, no global npm install -g, and HTTP(S) only to allowed hosts. npx -y <package> still works when the npm registry is an allowed host. See Python Sandbox.
• Secure authentication tokens: pass them through env or headers from Flow secrets
• Validate all inputs and outputs
• Use HTTPS for remote connections
• Implement proper error handling

Development Guidelines

• Document custom MCP tools thoroughly
• Implement proper logging and monitoring
• Use consistent input/output schemas
• Test tools thoroughly before deployment