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

> Discover how mcp.passive-inventory finds and inventories MCP capabilities in OpenWork by reading local configuration files. Get a static snapshot without remote calls.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: internals
- Published: 2026-08-22

---

**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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/mcp.ts)

The passive inventory logic lives in [`apps/server/src/mcp.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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

```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

```tsx
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.