How `mcp.passive-inventory` Discovers and Inventories MCP Capabilities in OpenWork

The mcp.passive-inventory routine generates a static, diagnostics-only snapshot of all configured MCP layers by reading local OpenWork configuration files, returning an McpInventoryInspection object tagged with the "passive-static-subset" scope to indicate no remote calls are made.

The different-ai/openwork repository implements a capability discovery system for Managed Capability Providers (MCP) that operates entirely offline. The mcp.passive-inventory feature inspects workspace configurations by parsing local JSON and YAML manifests, making it safe for CI environments and debugging scenarios where network access is restricted.

Core Implementation in apps/server/src/mcp.ts

The passive inventory logic lives in apps/server/src/mcp.ts around line 585, marked by the comment "Diagnostics-only passive inventory". The exported function passiveMcpInventory accepts a runtime instance and orchestrates the discovery process without establishing remote connections.

The implementation follows a three-phase pipeline:

1. Workspace Resolution – Determines the root directory of the current or temporary workspace.
2. Static Configuration Loading – Invokes runtimeOnlyMcpInventory(runtime) to walk local directories (including .openwork and openwork.config.json) and collect policy JSON, tool manifests, and layer descriptors.
3. Scope Tagging – Applies the "passive-static-subset" scope to each discovered layer and tool entry, signaling to downstream consumers that this data is strictly for inspection.

The runtimeOnlyMcpInventory Helper

This internal function gathers tool definitions from each configured layer by reading static files rather than invoking remote MCP endpoints. It aggregates built-in and custom tools into a runtime inventory object that reflects the workspace's declared capabilities.

The Passive Scope Marker

The string "passive-static-subset" serves as a critical safety mechanism. When attached to layers and tools, it instructs the rest of the OpenWork system that this inventory must not trigger live actions. This scope prevents accidental execution of tools during diagnostic operations.

Structure of the McpInventoryInspection Object

The function returns an object containing detailed sections about the workspace's MCP configuration:

• Layers – An array of all configured MCP layers, each annotated with the "passive-static-subset" scope identifier.
• Tools – Complete definitions for every tool available across layers, including parameters and descriptions parsed from local manifests.
• Policy – The effective workspace policy, encapsulating static restrictions and permission boundaries defined in configuration files.
• Resource-Policy – Resource caps and permission sets that apply to specific tools or layers.
• Availability Flag – The boolean passiveLocalLayersAvailable indicates whether the static snapshot was successfully constructed. If configuration files are missing or corrupted, this flag returns false and the routine may return a "passive runtime configuration snapshot unavailable" error.

Practical Usage Examples

Querying Inventory in TypeScript

import { getRuntime } from '@/runtime/runtime-db';
import { passiveMcpInventory } from '@/mcp';

async function auditMcpCapabilities() {
  const runtime = await getRuntime();
  const { inventory, passiveLocalLayersAvailable } = await passiveMcpInventory(runtime);
  
  if (!passiveLocalLayersAvailable) {
    console.error('Passive runtime configuration snapshot unavailable');
    return;
  }
  
  console.log(`Discovered ${inventory.layers.length} MCP layers`);
  inventory.tools.forEach(tool => {
    console.log(`- ${tool.name} (${tool.scope})`);
  });
}

auditMcpCapabilities();

React Diagnostics Panel Integration

import { useEffect, useState } from 'react';
import { passiveMcpInventory } from '@/mcp';
import { getRuntime } from '@/runtime/runtime-db';

export function McpInventoryPanel() {
  const [inventory, setInventory] = useState(null);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadInventory() {
      try {
        const runtime = await getRuntime();
        const result = await passiveMcpInventory(runtime);
        
        if (!result.passiveLocalLayersAvailable) {
          throw new Error('Passive snapshot unavailable');
        }
        
        setInventory(result.inventory);
      } catch (e) {
        setError(e.message);
      }
    }
    loadInventory();
  }, []);

  if (error) return <div className="text-red-600">Error: {error}</div>;
  if (!inventory) return <div>Loading...</div>;
  
  return (
    <section>
      <h3>Passive MCP Inventory</h3>
      <ul>
        {inventory.layers.map(layer => (
          <li key={layer.id}>{layer.id} — {layer.scope}</li>
        ))}
      </ul>
      <h4>Tools</h4>
      <ul>
        {inventory.tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
    </section>
  );
}

Testing and Validation

The test suite in apps/server/src/mcp.passive-inventory.test.ts validates the inventory logic across multiple edge cases. These tests create temporary workspaces with varying configurations to verify that:

• Missing layer descriptors are handled gracefully
• Policy restrictions are correctly parsed and included
• The passiveLocalLayersAvailable flag responds accurately to configuration errors
• Abort signals properly terminate inventory construction

Integration with Diagnostics UI

According to the source code in apps/server/src/agent-context-diagnostics.ts, the passive inventory powers the Agent Context Diagnostics panel. This component consumes the McpInventoryInspection object to display the current workspace's capability matrix without invoking remote servers.

Similarly, apps/server/src/connect-state.ts utilizes the inventory to render the Connect steering state. By relying on the static snapshot marked with "passive-static-subset", the UI can present available tools and layers even when the application is offline or when MCP servers are unreachable.

Summary

• mcp.passive-inventory operates as a diagnostics-only routine that never contacts remote MCP servers.
• The system walks local configuration files in .openwork directories and openwork.config.json to build a static capability manifest.
• Each discovered item is tagged with the ** "passive-static-subset" ** scope to prevent accidental execution during inspection.
• The passiveMcpInventory function in apps/server/src/mcp.ts returns both an McpInventoryInspection object and a passiveLocalLayersAvailable boolean flag.
• This approach enables safe capability discovery in air-gapped environments, CI pipelines, and offline debugging scenarios.

Frequently Asked Questions

Does mcp.passive-inventory make network requests to MCP servers?

No. The routine is explicitly designed to avoid network calls. It only reads static configuration files from the local workspace, making it suitable for environments without internet access or where remote connections are prohibited.

What happens if the workspace configuration is missing or corrupted?

If required configuration files are missing or invalid, the function sets passiveLocalLayersAvailable to false and returns an error indicating that the "passive runtime configuration snapshot unavailable". This signals to calling components that diagnostic data cannot be displayed.

How does the "passive-static-subset" scope affect tool execution?

The scope acts as a safety lock. When tools and layers carry this scope identifier, the OpenWork execution engine recognizes them as diagnostic metadata only and prevents any live invocation or side effects. This ensures that inventory inspection never triggers unintended tool runs.

Can I use passive inventory in CI/CD environments without network access?

Yes. Because mcp.passive-inventory relies solely on local file system reads via runtimeOnlyMcpInventory, it functions completely offline. This makes it ideal for validating workspace configurations in CI pipelines before deployment or for generating documentation in build processes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}