FlowState MCP

FlowState MCP is a local Model Context Protocol server for persistent business-workflow and application-state analysis during authorized web security testing.

It is not a vulnerability scanner and it does not send requests.

V1 imports local Burp XML or HAR traffic, assigns each import to a human-defined actor, strips authentication secrets, extracts workflow-relevant identifiers and state fields, builds an actor/entity/action/state graph, proposes hypotheses for manual validation, can persist structured validation outcomes, and can prioritize the highest-value unresolved hypotheses.

Why it exists

Burp MCP is excellent at exposing HTTP traffic and controlled Burp actions to an AI client.

FlowState solves a different problem:

What does the traffic mean in the application's workflow?

Examples:

Owner creates invitation
        ↓
Member accepts invitation
        ↓
Membership becomes active
        ↓
Owner removes member

FlowState can remember the actors, objects, transitions, and evidence behind those actions and then suggest questions such as:

• Was an accepted invitation actually made unusable?

• Can another registered actor perform the same state-changing action?

• Did a field change from pending to accepted, and are invalid adjacent transitions still untested?

• Where did one object identifier appear across multiple requests?

Those are hypotheses, not vulnerability findings.

Related MCP server: HAR-MCP

Design principle: no target-specific heuristics

A lab or real target may reveal a weakness in FlowState's model, but the production fix must describe a general web-workflow property, not the target's route names or known solution.

FlowState must not special-case paths such as /account, /checkout, /dashboard, or any lab-specific endpoint. Instead, it should reason from evidence such as:

• chronological timestamps;

• session continuity and session rotation;

• redirects and sanitized Referer relationships;

• HTTP method and response semantics;

• observed state fields;

• the same endpoint changing from a redirect/denial-like response to a successful response.

Regression fixtures are allowed to resemble bugs that exposed a weakness. Production code is not.

v0.1.3 workflow intelligence

v0.1.3 adds generic workflow-span reasoning on top of the v0.1.2 chronology model:

• redirect-follow GET/HEAD observations are identified as navigation edges;

• navigation that also rotates a session or carries state evidence remains a meaningful state boundary;

• the same endpoint changing from redirect to success is surfaced as an access-gate candidate;

• transition hypotheses are ranked by bug-hunting value;

• whole-span checkpoint hypotheses target the protected destination instead of only examining adjacent triples;

• low-value local skip hypotheses whose destination is merely a redirect-follow navigation request are suppressed.

For an observed span like:

resource denied
      ↓
workflow step A
      ↓
workflow step B
      ↓
resource succeeds

FlowState can ask whether the resource becomes accessible immediately after A, before B is completed, without knowing anything about the application's path names.

v0.1.4 evidence lifecycle

v0.1.4 keeps FlowState passive but lets it remember what happened when a human manually validates a generated hypothesis.

Generated hypotheses receive stable campaign-local IDs plus a validation state:

untested
   ↓
supported | falsified | inconclusive

flow_record_hypothesis_validation stores only structured, sanitized evidence such as:

• the hypothesis ID;

• manual outcome (supported, falsified, or inconclusive);

• test method and path;

• observed HTTP status;

• sanitized redirect path;

• a bounded note with obvious secret assignments redacted.

Query values are not persisted in validation paths. Cookies, session values, credentials, CSRF values, and token material are not required or intentionally stored.

A supported hypothesis still does not mean "confirmed vulnerability". It means manual evidence supported the security concern represented by that hypothesis. Reporting impact and vulnerability status remain separate human decisions.

The lifecycle becomes:

passive traffic
      ↓
workflow model
      ↓
hypothesis (untested)
      ↓
manual validation outside FlowState
      ↓
record structured result
      ↓
supported / falsified / inconclusive
      ↓
regenerated hypothesis keeps that history

v0.1.5 validation-aware queue

v0.1.5 uses the persisted validation history to answer a new question:

Given what has already been tested, what should I test next?

flow_next_hypotheses combines current transition and actor-comparison hypotheses, attaches their persisted validation status, and returns only actionable unresolved work.

Queue behavior is intentionally conservative:

• untested hypotheses keep their normal hunting priority;

• inconclusive hypotheses remain actionable but receive a small retry penalty;

• supported and falsified hypotheses remain visible in normal hypothesis/history output but are excluded from the next-action queue;

• an intermediate_state_access umbrella hypothesis does not compete with concrete workflow_checkpoint_access children for the same actor and destination;

• resolving one child hypothesis does not automatically mark its broader parent supported or falsified.

This is prioritization only. FlowState still does not send validation traffic.

v0.1.6 workflow dominance and subsumption

v0.1.6 prevents the next-action queue from recommending redundant workflow tests when a stronger earlier checkpoint has already been directly supported.

The rule is structural, not path-specific. For the same actor and destination, if a supported workflow_checkpoint_access hypothesis shows that the destination was already reachable at checkpoint A, then FlowState can safely treat certain later questions as queue-only subsumed work:

• a later workflow_checkpoint_access hypothesis whose checkpoint was still listed as a remaining prerequisite after A;

• a skip_step hypothesis for a prerequisite that was also still listed after A.

Example:

resource denied
      ↓
checkpoint A       ← directly tested: resource succeeds here
      ↓
checkpoint B       ← later checkpoint question is subsumed
      ↓
step C             ← skip-C question is subsumed for earliest-access reasoning
      ↓
resource succeeds

The important distinction is preserved:

validation_status: untested
queue_status: subsumed
subsumed_by: hyp-...

FlowState does not rewrite the later hypothesis to supported, because it was never directly tested. Subsumption only says another stronger result already answered the same earliest-access question well enough that another request would be redundant.

Subsumption is directional and scoped. A later supported checkpoint does not subsume an earlier checkpoint, and evidence does not cross actors or destinations.

flow_next_hypotheses now returns a separate subsumed collection and subsumed_count alongside the actionable queue.

V1 safety boundary

FlowState V1:

• uses local stdio MCP only;

• has no HTTP client;

• has no browser automation;

• has no scanner;

• has no exploit runner;

• does not replay requests;

• does not store Authorization, Cookie, Set-Cookie, API-key, password, or token values from imported traffic;

• filters imports to the campaign target host and its subdomains;

• uses bounded import sizes and bounded observation counts;

• labels hypotheses as requiring manual validation;

• records validation outcomes only after an external/manual test has already occurred;

• prioritizes unresolved hypotheses without changing their evidence state;

• can suppress redundant later workflow questions without marking them directly validated.

Use your existing Burp MCP separately when you intentionally want the AI client to inspect or replay a request.

Tools

Install

Python 3.11+:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
pytest -q

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q

Run manually

python server.py

The server speaks MCP over stdin/stdout, so manual launch normally appears to wait for protocol input.

Codex registration

Windows example:

codex mcp add flowstate -- D:/Tools/FlowState-MCP/.venv/Scripts/python.exe D:/Tools/FlowState-MCP/server.py
codex mcp get flowstate

Linux/macOS:

codex mcp add flowstate -- /absolute/path/FlowState-MCP/.venv/bin/python /absolute/path/FlowState-MCP/server.py

Claude Code registration

claude mcp add flowstate --scope user -- /absolute/path/FlowState-MCP/.venv/bin/python /absolute/path/FlowState-MCP/server.py

Suggested workflow with Burp MCP

ScopeNest containers
  ├─ Owner
  ├─ Member
  └─ Anonymous
        │
        ↓
       Burp
        │
        ├──────────────→ Burp MCP
        │                  │
        │                  └─ inspect/replay intentionally
        │
        └─ export HAR/XML
              │
              ↓
         FlowState MCP
              │
     ┌────────┼─────────┐
     ↓        ↓         ↓
   actors   objects   states
     └────────┼─────────┘
              ↓
          hypotheses
              ↓
      manual validation
              ↓
      record safe result
              ↓
   supported / falsified /
        inconclusive
              ↓
   resolve + subsume work
              ↓
      next unresolved work

Example session

1. flow_create_campaign
   name="Target SaaS"
   target_host="app.example.com"

2. flow_register_actor
   actor_id="owner"
   name="Owner"
   roles=["organization_owner"]

3. Export Owner traffic from Burp as XML or HAR.

4. flow_import_burp_xml

5. flow_build_state_graph

6. flow_generate_transition_hypotheses
   # note the hypothesis_id of the question you manually test

7. Perform the controlled validation separately.

8. flow_record_hypothesis_validation
   hypothesis_id="hyp-..."
   outcome="supported"
   test_method="GET"
   test_path="/protected-resource"
   observed_status=200

9. flow_generate_transition_hypotheses
   # the same hypothesis now reports validation_status="supported"

10. flow_next_hypotheses
    # supported/falsified work is retained as history
    # later questions may be queue_status="subsumed" when stronger earlier evidence covers them

11. flow_list_hypothesis_validations

What V1 deliberately does not do

V1 does not try to infer a complete business ontology from every API field.

It uses deterministic heuristics for:

• action verbs in paths;

• HTTP method semantics;

• path identifiers;

• common ID-like JSON fields;

• common state/status/role fields.

The graph is evidence-backed and intentionally imperfect. A future version can add explicit human corrections such as:

"mem_912 represents user_22"
"workspace_id is a tenant boundary"
"accepted invitations must never be reusable"

without turning guesses into facts.

V1 success test

FlowState V1 is successful only if, on a real bug-bounty session, it produces at least one hypothesis that you would genuinely test and that you did not immediately notice from raw Burp history alone.

The next bar is stronger: the hypothesis should survive controlled manual validation, FlowState should preserve that evidence without turning a hypothesis into a vulnerability claim automatically, and later prioritization should avoid spending requests on workflow questions already covered by stronger evidence.

License

MIT