Bridge Reference

Technical reference for the Bridge graph, nodes, ports, pipelines and endpoint. For a step-by-step guide see the Bridge Overview page.

Endpoint

https://mcp.fainflow.com/mcp/<bridgeId>

Path	What it serves
`/mcp`	Your full federation — every tool from every connection.
`/mcp/<bridgeId>`	One Bridge — its federated tools plus its pipelines.

Both speak MCP over Streamable HTTP. Authentication is OAuth at the edge (your Fainflow login); the Bridge resolves to your account automatically and scopes every call to the connections and pipelines you own.

Auditing

Every tools/call that reaches a handler is written to the append-only audit log (listing — initialize, tools/list — is not). Each entry records:

Field	Value
action	`mcp.tool_call` or `mcp.pipeline_call`
actor	the authenticated Fainflow user (id + email)
resource	the tool / pipeline name
scope	`federation` or `bridge:<id>`
mutating	`true` for write-shaped tools (create/update/delete/merge/push/…)
args	identifiers only (owner, repo, path, query, cloudId, …); other values reduced to type/length, secrets dropped — free-text payloads are never stored
status	`success` / `failure`, plus duration

The trail is append-only (no update/delete) and visible in Audit Logs in the dashboard. Logging is fire-and-forget — it never adds latency to or fails a call.

Node kinds

Kind	Role	Ports
`input`	Pipeline entry point.	Output ports = the named arguments the caller passes.
`tool`	One tool call on a connection.	Inputs = tool arguments, output = its result. Fixed by the tool schema.
`merge`	Fan-in — combine inputs into one object.	Inputs you add; one combined output.
`output`	Pipeline exit point.	Input ports = what the caller receives back.
`transform`	Reserved for value reshaping between nodes.	—

Port rules

You add/remove ports on input nodes (arguments) and output / merge nodes (results) in the inspector.
Tool node ports are fixed — they come from the tool's input schema.
An edge wires one node's output port → another node's input port. The graph must be acyclic; a cycle is rejected at draw time and at save time.

Pipelines

A pipeline is a named subgraph: an inputNode, an outputNode, and every node in between that the output depends on.

{
  "id": "p1",
  "name": "get_repo_context",   // what the agent calls
  "description": "…",
  "inputNode": "in1",            // its output ports become the call arguments
  "outputNode": "out1"           // its input ports become the result
}

When called, the Bridge scopes execution to the nodes the outputNode actually depends on, then runs them.

Execution

Order is derived from the graph. Nodes are run in dependency waves (topological levels); nodes in the same wave run in parallel.
Each tool call opens a fresh session, calls the tool, and closes it.
Inputs that resolve to undefined are dropped; a node's call arguments are { ...config, ...inputs }.
Fail-fast. If any node fails, the run stops with node <id> (<tool>) failed.
Per-call timeout: 30s. Max nodes per run: 50.

Graph shape

The Bridge stores one graph object:

{
  "version": 1,
  "nodes": [
    {
      "id": "in1",
      "kind": "input",
      "outputs": ["query"],
      "position": { "x": 280, "y": 40 },
      "label": "Input"
    },
    {
      "id": "t1",
      "kind": "tool",
      "connectionId": "<connId>",
      "tool": "search_repositories",
      "inputs": ["query"],
      "outputs": ["result"]
    },
    { "id": "out1", "kind": "output", "inputs": ["ctx"] }
  ],
  "edges": [
    { "id": "e1", "from": { "node": "in1", "port": "query" },
                  "to":   { "node": "t1",  "port": "query" } },
    { "id": "e2", "from": { "node": "t1",  "port": "result" },
                  "to":   { "node": "out1","port": "ctx" } }
  ],
  "pipelines": [
    { "id": "p1", "name": "find", "inputNode": "in1", "outputNode": "out1" }
  ]
}

Validation

A saved graph is rejected if it has:

a malformed shape, or duplicate node/edge ids;
an edge or pipeline that references a missing node;
a tool name that isn't ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$;
a pipeline whose boundaries aren't valid input/output nodes;
a cycle.

Limits

Limit	Value
Nodes per run	50
Per-tool-call timeout	30s
Tool name pattern	`^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
Graph	must be acyclic