Skip to content

mcp-validation-guide.md

Latest commit

 

History

History
112 lines (82 loc) · 4.65 KB

mcp-validation-guide.md

File metadata and controls

112 lines (82 loc) · 4.65 KB
Raw

Dual MCP Validation Guide

This guide validates real local FlowLens MCP calls. It does not use Replay fixtures as a substitute for Connected runtime evidence.

What Is Running

The development stack contains two internal-only Streamable HTTP MCP services:

Service MCP tools Data boundary
SQLite Analytics schema_overview, describe_table, query_readonly A seeded local demonstration SQLite database; SQL is allowlisted and read-only.
FlowLens Inspector health_check, list_runs, get_run_diagnostics, get_timeline_window, compare_runs Gateway AgentOps APIs, with Gateway retaining user, tenant, and run-owner checks.

The services have no host-port mappings. The Runtime discovers their schemas with a service token, then exchanges the current user_id and run_id for a short delegated token when executing an MCP tool. The model never receives a token.

Isolated Docker Start

From the repository root in PowerShell:

$env:DEER_FLOW_ROOT = (Get-Location).Path
$env:HOME = $env:USERPROFILE
$env:DEER_FLOW_CONTAINER_PREFIX = "flowlens-agentops"
$env:DEER_FLOW_HTTP_PORT = "2027"

docker compose -p flowlens-agentops `
  -f docker/docker-compose-dev.yaml `
  -f docker/docker-compose-agentops-isolated.yaml `
  up -d --build --remove-orphans frontend gateway nginx sqlite-analytics flowlens-inspector

The bootstrap container generates a local-only RSA keypair in a Docker named volume. The isolated DeerFlow runtime state is stored under the ignored backend/.flowlens-agentops/ directory, so an older local schema cannot affect this stack. 2027 avoids interrupting an existing DeerFlow environment on 2026.

Check the stack:

docker compose -p flowlens-agentops `
  -f docker/docker-compose-dev.yaml `
  -f docker/docker-compose-agentops-isolated.yaml ps
Invoke-RestMethod http://localhost:2027/health

Open http://localhost:2027/, sign in or create a local account, then open http://localhost:2027/agentops in another tab.

Demo 1: Real SQLite MCP Call

In DeerFlow, send this prompt:

Use the SQLite Analytics MCP to inspect the available schema, then count runs by status.
State the SQL you used and label the result as local demonstration data.

Expected behavior:

  1. The Lead Agent selects sqlite_analytics_schema_overview.
  2. It may call sqlite_analytics_describe_table for agent_runs.
  3. It calls sqlite_analytics_query_readonly with a single SELECT.
  4. The MCP result returns as a ToolMessage; the Lead Agent summarizes it.
  5. AgentOps shows the new run_id with MCP Timeline items and mcp.tool.start / mcp.tool.end events.

For a negative case, ask for DELETE FROM agent_runs. The server rejects it before database execution. This verifies both the SQL policy and the failure evidence path; it is not a production security benchmark.

Demo 2: Inspect a Prior Run Through MCP

After Demo 1 finishes, use its run_id and thread_id from AgentOps. Start a new DeerFlow chat and send:

Use FlowLens Inspector MCP to list my recent runs. Inspect the diagnostics and a Timeline window for run_id <RUN_ID> in thread_id <THREAD_ID>. Summarize the status, token count, tool/MCP evidence, and deterministic root cause. Do not invent evidence not returned by the tools.

Expected behavior:

  1. The Runtime discovers the Inspector schema with a discovery-only token.
  2. For the selected MCP tool call, it obtains a short delegated token bound to the current user and new run.
  3. Inspector validates that token and forwards it to Gateway.
  4. Gateway independently checks the authenticated user, tenant, and target run ownership.
  5. The returned diagnostics become the new Agent run's ToolMessage, so the second run contains its own MCP evidence.

AgentOps Walkthrough

For each completed run:

  1. Select the run in Run Explorer.
  2. Confirm the summary bar: duration, tokens, Tool/Error count, MCP count, and terminal status.
  3. Select the MCP Timeline filter. Open an item to inspect safe metadata such as server name, tool name, transport, span, parent span, and duration.
  4. Use Root Cause. It is deterministic: the optional explanation can describe the result but cannot change it.
  5. Use Export to download the redacted JSON snapshot.

Stop the Isolated Stack

docker compose -p flowlens-agentops `
  -f docker/docker-compose-dev.yaml `
  -f docker/docker-compose-agentops-isolated.yaml down

The MCP key volume and the ignored backend/.flowlens-agentops/ runtime state retain local demonstration data between restarts. Add -v to remove the Docker volumes; remove backend/.flowlens-agentops/ separately when a fully fresh local identity is required.