AI Agent Orchestration

Use nfltr mcp as the planner-side control plane, run nfltr worker on remote machines, and attach each worker to a local MCP-capable tool such as Claude or GitHub Copilot CLI. NFLTR handles discovery, worker probing, encrypted A2A task streams, and direct artifact handoff while your planner decides which worker should do what.

What Runs Where

1. Start the Planner-Side MCP Bridge

On the machine running your MCP client, start nfltr mcp and point it at both the NFLTR HTTP API and the gRPC control plane.

nfltr mcp \
  --proxy-url https://nfltr.xyz \
  --server grpc.nfltr.xyz:443 \
  --api-key "$NFLTR_API_KEY" \
  --a2a-e2ee

If you want to wire it straight into VS Code, generate the MCP config instead:

nfltr mcp \
  --proxy-url https://nfltr.xyz \
  --server grpc.nfltr.xyz:443 \
  --write-mcp-json .vscode/mcp.json

When the A2A connection is available, this server exposes both raw discovery tools and the orchestration tool set:

• list_my_peers for the raw peer inventory under your key
• list_worker_peers for worker-filtered peers with resource labels
• probe_worker for live capacity, available slots, and protocol support
• orchestrate_task to start a bidirectional worker task
• get_task_status to inspect progress, questions, errors, or results
• respond_to_worker to answer a question or attach follow-up artifacts
• cancel_task and list_active_tasks for session control

2. Start Worker Machines

Each worker is just an NFLTR A2A agent with a local MCP server behind it.

Claude-backed worker

nfltr worker \
  --server grpc.nfltr.xyz:443 \
  --api-key "$NFLTR_API_KEY" \
  --labels gpu=a100,repo=payments,zone=eu-west \
  --max-tasks 2 \
  --mcp-command "claude mcp serve"

Copilot-backed worker

nfltr worker \
  --server grpc.nfltr.xyz:443 \
  --api-key "$NFLTR_API_KEY" \
  --labels repo=payments,tool=copilot,device=laptop \
  --max-tasks 1 \
  --mcp-command "nfltr copilot-mcp --cwd ~/projects/payments --model gpt-5.2 --reasoning-effort high"

Workers automatically advertise labels that planners can use for selection:

3. Run the Orchestration Cycle

A typical planner loop looks like this:

One practical task payload looks like this:

{
  "agent_id": "worker-gpu-01",
  "task_id": "release-report-20260414",
  "objective": "Generate a release summary and attach a markdown report",
  "context": {
    "service": "payments-api",
    "branch": "release/2026-04-14",
    "checks": ["unit", "smoke", "security"]
  },
  "constraints": {
    "max_minutes": 15,
    "must_include": ["risks", "rollback plan"]
  },
  "artifact_files": [
    "./artifacts/test-summary.json",
    "./artifacts/changelog.txt"
  ],
  "timeout_ms": 120000
}

After fan-out, your planner can optionally send one more aggregation task to a collector worker or combine the returned outputs locally.

4. Handle Task State and Recovery

Two behavior details matter in real workflows:

• orchestrate_task can move from accepted to waiting_input, running, or even completed very quickly, so planners should tolerate fast state transitions.
• Provide your own stable task_id whenever retries or resume logic matter. Treat that identifier as the planner-side idempotency key for the work item.

5. Move Files and Generated Outputs

Use artifact_files when you want NFLTR to stream local files directly over the existing A2A task stream instead of uploading them to a server-managed URL.

• Planner-side local paths are chunked over A2A when the transport is a2a-chunk.
• The worker receives receiver-local materialized files before the local MCP tool sees them.
• Returned artifacts come back the same way, with planner-local materialized paths once the inbound transfer finishes.
• For very large datasets, keep the task stream for control and move the bulk payload through P2P or object storage with a digest in the task result.

This lets the planner keep prompts small while still attaching build logs, screenshots, test reports, generated binaries, or patch bundles to the worker run.

6. Security and Relay Visibility

nfltr mcp enables A2A payload encryption by default with --a2a-e2ee=true.

• NFLTR can still see source and target agent IDs, timing, and ciphertext sizes so it can route the stream correctly.
• NFLTR cannot read the objective, context, follow-up messages, or chunked artifact contents inside the encrypted A2A frames.
• If you turn encryption off for debugging, do it deliberately and only for non-sensitive workflows.

This is the right default for code review, deployment planning, security triage, or any workflow where the relay should stay blind to task contents.

When to Use This Pattern

Related Reading

• CLI Reference: nfltr mcp — planner-side MCP bridge flags and generated VS Code config.
• Agent-to-Agent Communication — the underlying A2A transport model.
• End-to-End Encryption — what the relay can and cannot see.
• Remote AI Workstation — publish one laptop-hosted AI session directly.
• Managed Capabilities — dashboard-driven route and runtime control for long-lived agent surfaces.