MCP worker tools

Jarvis gives supported worker runtimes a small MCP tool surface so they can communicate with the orchestrator without dumping raw terminal output into the main chat.

These tools are designed for low-noise, structured coordination.

Purpose

Worker MCP tools exist so a runtime can:

• report progress at meaningful milestones
• surface a block immediately
• ask the human for a decision
• request more context from Jarvis
• optionally query a personal knowledge base if one is configured

In the default experience, these tools are injected automatically for supported worker sessions.

Transport model

Jarvis exposes worker tools over MCP JSON-RPC using an HTTP transport.

High-level properties:

• worker-to-Jarvis communication is structured
• most worker tool calls are attributed to a session_id
• uplink tool calls are also inserted into the main chat so the operator sees them inline
• the optional knowledge-base lookup is different: it is read-only and does not post to the main chat

report_progress

Use this when a worker reaches a milestone, finishes a subtask, or changes status.

Inputs:

• session_id
• status: working, blocked, completed, or needs_review
• detail

Behavior:

• records a structured progress update
• inserts a progress message into the main chat
• can trigger follow-up orchestration behavior for non-routine states such as completion or blockage

Use it for meaningful progress, not for noisy heartbeat spam.

notify_blocked

Use this when the worker cannot proceed without outside help, access, or a decision.

Inputs:

• session_id
• reason
• optional context

Behavior:

• surfaces the block in the main Jarvis chat
• is suitable for mobile or remote operators who are not watching the terminal
• is intended for real blockers, not minor uncertainty

ask_human

Use this when the worker needs a human decision, clarification, or approval.

Inputs:

• session_id
• question
• optional urgency: low, normal, high, critical

Behavior:

• alerts the human through the main chat
• returns an acknowledgement to the worker
• does not synchronously deliver the human answer in the tool response

Workers should keep enough context visible in their own session so the human can respond by intervening there if needed.

request_context

Use this when the worker needs more information from Jarvis instead of guessing.

Inputs:

• session_id
• query

Behavior:

• asks Jarvis for additional context
• surfaces the request in the main chat
• returns a best-effort context response to the worker

Typical use cases include checking surrounding task state, asking about active sessions, or requesting project background.

Optional search_kb

search_kb is an optional personal knowledge-base lookup tool.

Important differences from the uplink tools:

• it is sessionless
• it is read-only
• it does not post a message into the main chat

The intended use is self-service retrieval of durable personal context such as preferences, prior decisions, or local project notes.

Graceful unavailable behavior

Jarvis treats the knowledge base as optional.

If no knowledge base is configured, search_kb should fail open with an explicit unavailable-style result rather than breaking the worker session. Workers can call it safely without first hard-coding whether the feature exists.

This keeps the public contract stable across installations that do and do not use a knowledge base.

Privacy boundary

These tools are coordination primitives, not a license to mirror full terminal transcripts into the main chat.

Jarvis’s design goal is to keep orchestration context compact:

• summary capsules carry a lightweight snapshot
• worker MCP tools carry structured signals
• raw worker output stays in the worker session unless explicitly needed

Related references

• API reference
• SSE events