picatz / picatz/flowstate

Design: MCP in both directions — agents drive Flowstate, and workflows call any MCP server's tools

Open
#108 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design engine kind/design-record
Dominant language
Go
Stars
9
Forks
0
Avg merge
3h 3m
Merged PRs (30d)
509

Description

One direction already ships: flow mcp exposes the control plane to agents, tool schemas derived from the request descriptors (#89). This issue is the other direction — Flowstate consuming MCP servers — and the bridge that makes both "just work" locally and in the cloud.

The key fit: an MCP bridge is just a plugin

The plugin protocol already does the hard part. A plugin advertises tasks as TaskManifests carrying serialized protobuf descriptors, and the host reconstructs them so validation, completion, and dispatch treat the task as native. An MCP server advertises tools as JSON Schemas. So one bridge plugin — flowstate-plugin-mcp — connects to any configured MCP server, lists its tools, synthesizes descriptors from the JSON Schemas (the descriptor bytes in a manifest are built at runtime anyway; a FileDescriptorProto constructed from a JSON Schema is mechanical for the object/string/number/bool/array core), and serves each tool as a task:

steps:
  - id: lookup
    mcp.github_search_issues:      # any tool from any configured MCP server
      query: "label:bug is:open"

Every MCP server in existence becomes a Flowstate task provider without anyone writing a plugin for it. The ecosystem math changes: #95's roster is the curated, credential-hardened tier, and the MCP bridge is the long tail.

What the bridge must be honest about:

  • Type fidelity. JSON Schema is looser than protobuf (unions, additionalProperties, conditional schemas). Map the clean core; degrade the rest to a Value-typed input with the schema carried as documentation rather than lying with a wrong descriptor — the same "better absent than wrong" rule the LSP applied to macro signatures.
  • Durability semantics. MCP tools declare no idempotency. Default every bridged task to the posture http gives non-idempotent methods (no retry on unknown outcome unless the author opts in), because a retried create_ticket is two tickets.
  • Transports. stdio-launched MCP servers are child processes the bridge supervises (the plugin host's own launch discipline, one level down); HTTP/SSE servers are egress governed by netpolicy like any other outbound call. Local and remote fall out of the same config.
  • Policy. A bridged tool is arbitrary third-party capability; the #104 scope ladder applies (which MCP servers a deployment permits, which tools, per namespace/workflow/step), and the bridge's own config is the natural allowlist seam. Credentials to MCP servers ride the secrets story (#91), never inline config.

The triangle that unlocks agentic workloads

With both directions plus #95's llm plugin, three compositions exist, and the third is the differentiator:

  1. Agent drives Flowstate (flow mcp, shipped): Claude authors, validates, submits, watches.
  2. Workflow calls MCP tools (this bridge): a runbook step queries a vendor's MCP server.
  3. Durable agent: an llm-plugin step runs a tool-calling loop whose tools are MCP tools via the bridge — the agent's conversation is workflow state, surviving crashes, waiting on wait_for_signal: approval gates before dangerous tool calls, every tool invocation policy-checked and audited. That is "agentic pipelines with approval gates" from the README's own positioning, made concrete: Temporal's durability wrapped around an agent loop, with MCP as the tool surface and CEL policy as the cage.

Sequencing

Bridge after #91 (secrets, for MCP server credentials) and alongside #95's llm plugin; the tool-allowlist config lands with it, not after (a bridge that exposes every tool of every server on day one is #100's problem statement in miniature). flow mcp needs nothing — it already ships.

Related: #95 (llm plugin, the loop-runner), #100/#104 (policy over bridged capability), #91 (credentials), #97 (distribution — the bridge is itself a plugin an OCI pull should fetch).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing plugin protocol and the shipped flow mcp implementation, especially how TaskManifest descriptors are reconstructed and dispatched. The issue names no specific files or tests, so map the bridge design across plugin hosting, policy, secrets, and transport handling before implementation. Done means a reviewed design and implementation plan covering schema fidelity, durability, allowlists, credentials, and both MCP transports.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, backend, devtools, networking, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.