Agent Context Projection in OpenWork: How AI Agents See Your Workspace

Agent context projection is the mechanism that captures a snapshot of available workspace tools, queries the underlying MCP provider for concrete capabilities, and normalizes the response into a typed structure that AI agents can consume to determine which tools are available, missing, or limited.

Agent context projection forms the bridge between a user's workspace configuration and the AI agents that operate within it. In the OpenWork framework (different-ai/openwork), this feature aggregates extension capabilities, validates them against the provider's advertised tools, and surfaces any discrepancies to the agent runtime. By implementing a structured projection pipeline in TypeScript, OpenWork ensures that remote assistants receive accurate, up-to-date context about the tools they can invoke.

What Is Agent Context Projection?

Agent context projection is the three-stage pipeline responsible for manifesting the current workspace state into a format consumable by AI agents. Unlike static configuration files, this projection dynamically evaluates which tools are actually present, which are advertised by the Model Context Protocol (MCP) provider but missing, and whether any limitations or errors prevent tool execution. The system exposes this information through the /health and /reconcile endpoints, allowing agents to adapt their behavior before attempting tool calls.

Core Implementation

The implementation spans the TypeScript type definitions in packages/types and the health-check orchestration in apps/server.

Deriving Logical Projections

The pipeline begins by transforming raw workspace objects into searchable projection metadata. In packages/types/src/den/connect-diagnostics.ts, the deriveProjection function accepts an object—such as a plugin or connector—and generates a standardized projection containing a title, description, and searchText derived from the object's type and value.

// Located in packages/types/src/den/connect-diagnostics.ts
const proj = deriveProjection({
  objectType: 'plugin',
  value: { id: 'my-plugin', name: 'My Plugin' }
});
// Returns: { title: 'My Plugin', description: '...', searchText: 'my-plugin ...' }

This logical projection serves as the foundation for downstream provider queries, ensuring that each tool or extension is represented by consistent, queryable metadata.

Capturing Provider Snapshots

Once logical projections are established, OpenWork queries the MCP provider to determine which tools are actually available. The response conforms to the ProviderProjectionSnapshot interface, defined in packages/types/src/den/provider-projection.ts. This snapshot captures the ground truth from the provider with the following fields:

• source: Origin identifier of the projection request.
• checked: Boolean indicating whether the provider was successfully queried.
• provider and model: Identifiers for the specific provider and model configuration.
• present: Array of tools confirmed to be available.
• missing: Array of tools advertised in the logical projection but not found on the provider.
• limitation: Optional string describing partial capability restrictions.
• error: Optional error message if the provider query failed.

Normalizing Tools for the Agent

The final stage translates the raw ProviderProjectionSnapshot into a consumable view. In apps/server/src/cloud-mcp-health.ts, the function experimentalProviderToolsFromProjection performs this normalization, returning a CloudMcpExperimentalProviderToolsSnapshot object.

This function handles three critical responsibilities:

1. Missing Tool Resolution: Flags tools listed in missing so the agent knows not to invoke them.
2. Error Propagation: Surfaces any provider-side errors stored in the error field.
3. Capability Flagging: Sets the includesMcpTools boolean to indicate whether the projection contains valid MCP tool definitions or should be considered untrustworthy.

// Located in apps/server/src/cloud-mcp-health.ts
const mcpTools = experimentalProviderToolsFromProjection(providerSnap);
// Returns: { present: [...], missing: [], limitation?: string, error?: string, includesMcpTools: boolean }

Health Checks and Error Handling

When the projection reveals discrepancies—such as provider_tool_projection_missing or provider_projection_unavailable—the health-checking routine records a structured failure object. This object includes a stage: "provider_projection" identifier and a specific error code, which is then exposed via the health and reconcile API endpoints.

The system distinguishes between:

• Missing tools: Tools defined in the workspace but not returned by the provider.
• Provider errors: Complete failure to reach or authenticate with the provider.
• Limitations: Partial availability where the provider supports the tool but with restricted functionality.

These states are rigorously validated in the test suite, specifically in apps/server/src/cloud-mcp-health.test.ts and the end-to-end scenarios in apps/server/src/cloud-mcp-reconcile.e2e.test.ts.

Practical Implementation Example

The following example demonstrates the complete flow from logical derivation to normalized MCP tools:

import { deriveProjection } from '@/packages/types/src/den/connect-diagnostics';
import { experimentalProviderToolsFromProjection } from '@/apps/server/src/cloud-mcp-health';

// Stage 1: Derive logical projection for a workspace extension
const logicalProj = deriveProjection({
  objectType: 'connector',
  value: { id: 'slack-connector', name: 'Slack Integration' }
});

// Stage 2: Assume providerSnap is fetched from MCP provider
const providerSnap = {
  source: 'openai',
  checked: true,
  provider: 'openai',
  model: 'gpt-4o',
  present: ['slack_post_message'],
  missing: ['slack_archive_channel'],
  limitation: undefined,
  error: undefined
};

// Stage 3: Normalize for agent consumption
const agentView = experimentalProviderToolsFromProjection(providerSnap);
// agentView.includesMcpTools === true
// agentView.missing contains 'slack_archive_channel'

Summary

• Agent context projection dynamically maps workspace tools to provider capabilities through a typed TypeScript pipeline.
• The deriveProjection function in packages/types/src/den/connect-diagnostics.ts creates searchable metadata from workspace objects.
• ProviderProjectionSnapshot captures the provider's ground truth, including present tools, missing tools, and errors.
• experimentalProviderToolsFromProjection in apps/server/src/cloud-mcp-health.ts normalizes snapshots for agent consumption and sets reliability flags.
• Failure modes—such as missing tools or provider errors—are recorded with specific error codes and exposed through health endpoints to inform agent decision-making.

Frequently Asked Questions

What triggers an agent context projection update?

OpenWork refreshes the projection whenever the workspace configuration changes—such as when a new extension is installed—or when the health-check endpoint is polled. The system calls the MCP provider's /experimental/tool endpoint to ensure the snapshot reflects the current provider state.

How does OpenWork handle missing tools in a projection?

When a tool appears in the logical projection but is absent from the provider's response, it is populated in the missing array of the ProviderProjectionSnapshot. The experimentalProviderToolsFromProjection function propagates this list to the final snapshot, allowing agents to disable or hide unsupported functionality rather than attempting failed invocations.

What distinguishes deriveProjection from experimentalProviderToolsFromProjection?

deriveProjection operates on static workspace metadata to create a logical, searchable representation of a tool or extension. experimentalProviderToolsFromProjection operates on the dynamic response from the MCP provider, validating which logical tools actually exist and surfacing provider-specific errors or limitations.

Where are projection failures recorded in the OpenWork architecture?

Failures are captured in the health-check orchestrator within apps/server/src/cloud-mcp-health.ts. The system generates failure objects with a stage property set to "provider_projection" and specific error codes like provider_tool_projection_missing. These records are exposed via the /health and /reconcile endpoints and are validated by the test suites in apps/server/src/cloud-mcp-health.test.ts and apps/server/src/cloud-mcp-reconcile.e2e.test.ts.

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