Fluxor-MCP: Bridging Fluxor Workflows with the MCP Protocol

Fluxor-MCP is an adapter that turns every Fluxor action into an MCP tool and vice-versa. It lets you

• run Fluxor workflows from the command line,
• serve those workflows through an MCP server so that they can be consumed by other processes (e.g. LLM agents), and
• import remote MCP endpoints and use their tools as if they were native Fluxor actions.

Fluxor-MCP therefore provides a single, unified execution surface whether the logic lives inside your Go binary, in another process on the local host, on a remote machine – or a mix of all three.

---

Table of Contents

1. Key Features
2. Architecture Overview
3. Getting Started
4. Command-line Interface
5. Configuration
6. Examples
7. Contributing
8. License

---

Key Features

• Unified registry – Fluxor actions and MCP tools share the same namespace so that every component can be called through both interfaces.
• Automatic schema generation – Action input/output types are converted to JSON-schema so that MCP clients get proper validation & tooltips.
• Built-in action discovery – Common Fluxor services (printer, system/exec, …) are loaded automatically; wildcard or prefix selection is supported.
• Dynamic client import – Point the CLI at a remote MCP server and all of its tools are available instantly inside your workflow.
• Ready-to-use CLI – Run workflows, start a server, inspect actions/tools or add remote clients without writing any Go code.

Architecture Overview

┌────────────┐           import             ┌────────────┐
│  Remote    │ ───────────────────────────▶ │  Fluxor    │
│  MCP       │  (MCP protocol)              │  Runtime   │
│  Server    │                              └─────┬──────┘
└────────────┘                                   │ actions ↔ tools
      ▲                                          ▼
      │                               ┌──────────────────────┐
      │ serve MCP tools               │   Fluxor-MCP         │
      └──────────────────────────────▶│   Service & CLI      │
                                      │  – tool registry     │
                                      │  – server adapter    │
                                      └─────────┬────────────┘
                                                │
                                                ▼
                                      ┌──────────────────────┐
                                      │   Built-in Actions   │
                                      │  (printer, exec, …)  │
                                      └──────────────────────┘

1. Fluxor-MCP Service – wraps a standard Fluxor runtime and keeps a global tool registry that is shared by every incoming/outgoing MCP connection.
2. Server Adapter – exposes the registry via HTTP/SSE.
3. Client Importer – connects to foreign MCP servers, introspects their tools and registers thin proxy actions on the local Fluxor instance.

Getting Started

Installation

go get github.com/viant/fluxor-mcp@latest

# optional – install the standalone CLI
go install github.com/viant/fluxor-mcp/cmd/fluxor-mcp@latest

Minimal Example (library usage)

package main

import (
    "context"
    "fmt"

    mcp "github.com/viant/fluxor-mcp/mcp" // import path for the service
)

func main() {
    ctx := context.Background()

    // Create a new service with default configuration. All built-in actions
    // (printer, exec, ...) are loaded automatically.
    svc, err := mcp.New(ctx)
    if err != nil {
        panic(err)
    }

    // Use the embedded Fluxor runtime just like you would without MCP.
    rt := svc.WorkflowRuntime()

    workflow, _ := rt.LoadWorkflow(ctx, "parent.yaml")
    _, wait, _ := rt.StartProcess(ctx, workflow, nil)
    output, _ := wait(ctx, 0)
    fmt.Printf("workflow finished: %+v\n", output)
}

Command-line Interface

The fluxor-mcp binary is a thin wrapper around the service above and covers the most common tasks. Run fluxor-mcp --help to see the full list of options.

Usage: fluxor-mcp [global options] <command> [command options]

Global Options:
  -f, --config <file>   Service configuration YAML/JSON path (optional)

Commands:
  run            Run a workflow                 (see `run --help`)
  serve          Start an MCP server            (see `serve --help`)
  add-client     Register remote MCP endpoint   (see `add-client --help`)
  exec           Execute a tool/action once     (see `exec --help`)
  list-tools     List all registered tools      (service/method)
  list-actions   List Fluxor services & actions
  tool           Show detailed info about one tool
  action         Show detailed info about one action

Selected Sub-commands

1. Run a workflow locally

   fluxor-mcp run -l examples/hello.yaml -s '{"name":"World"}'

2. Expose tools over HTTP (defaults to :5000)

   fluxor-mcp serve -f config.yaml

3. Import tools from a remote server

   fluxor-mcp add-client \
     --name prod \
     --address https://mcp.example.com/tools \
     --version v1
   

4. Execute a tool once

   The -n/--name flag accepts multiple notation styles that all refer to the same underlying tool. Pick whichever feels most natural – the CLI normalises it automatically.

   # Canonical underscore/dash notation (service_…-method)
   fluxor-mcp exec -n system_exec-execute -i '{"commands":["echo hello"]}'
   
   # Slash + dot  (service/path.method)
   fluxor-mcp exec -n system/exec.execute -i '{"commands":["echo hello"]}'
   
   # Slash + dash (service/path-method)
   fluxor-mcp exec -n system/exec-execute -i '{"commands":["echo hello"]}'
   
   # Fully slash separated (service/path/method)
   fluxor-mcp exec -n system/exec/execute -i '{"commands":["echo hello"]}'

   Supplying an unknown tool now fails fast with a clear error instead of hanging.

Configuration

All features can be used without a configuration file. When present, the YAML shown below illustrates the available knobs.

# config.yaml

# 1) Built-in actions – choose any subset by exact match, prefix or wildcard
builtins:
  - "*"            # ← load every built-in service (default when omitted)
  # - "printer"   # single service
  # - "system/"   # prefix – everything underneath system/

# 2) MCP Server options used by the `serve` command (all fields optional)
server:
  transport: "http"     # http | ws | stdio | … (see github.com/viant/mcp)
  port: 6000            # default 5000

# 3) Remote MCP endpoints to import on startup
mcp:
  items:
    - name: analytics
      version: v1
      transport:
        type: sse
        url: https://analytics.example.com/tools

#   Alternatively load the list from another file/URL:
# mcp:
#   url: file://externals.yaml

Examples

Clone the repository to get a couple of ready-to-run examples:

git clone https://github.com/viant/fluxor-mcp.git
cd fluxor-mcp

# Run the hello-world workflow
go run ./cmd/fluxor-mcp run -l examples/hello.yaml -s '{"name":"Bob"}'

# Start a local MCP server and play with the tool registry
go run ./cmd/fluxor-mcp serve

# Inspect available tools / actions
go run ./cmd/fluxor-mcp list-tools
go run ./cmd/fluxor-mcp list-actions

# Execute a single tool locally (prompt user for input)
go run ./cmd/fluxor-mcp exec -n input-ask -i '{"Message":"what is your favourite city"}'

Contributing

Issues and pull requests are welcome! Please open an issue first to discuss the intended change when you plan to work on larger features so that we can avoid duplicate effort.

License

Fluxor-MCP is licensed under the Apache 2.0 license. See the LICENSE file for details.

---

© 2012-2023 Viant, Inc. All rights reserved.