What Is the OpenWork MCP Registry Used For?

The OpenWork MCP registry is the authoritative catalog of Model Context Protocol (MCP) provider descriptors that the OpenCode AI-agent runtime queries to discover and invoke tools, resources, and UI bindings.

The OpenWork MCP registry functions as the backend index for native MCP applications within the different-ai/openwork ecosystem. Unlike traditional implementations that expose provider metadata directly to language models, OpenWork employs a proxy architecture that keeps sensitive provider descriptors hidden while still enabling sophisticated tool discovery and execution through controlled interfaces.

Core Purpose of the OpenWork MCP Registry

At its foundation, the OpenWork MCP registry stores provider descriptors for servers that advertise the io.modelcontextprotocol/ui extension. These descriptors define available tools, resource schemas, and UI bindings that the OpenCode runtime can invoke. The registry serves as the source of truth for what capabilities exist and how they should be called.

According to the source code in docs/features/remote-mcp-apps/README.md, the registry operates as a model-visible catalog. However, OpenWork deliberately avoids writing provider entries directly into the OpenCode runtime’s registry. Instead, the desktop client maintains provider-specific data in a private, non-public App-host credential. This design ensures that sensitive metadata—such as internal resource URIs and provider configurations—never reaches the model’s context window.

Architectural Design and Security Model

OpenWork’s interaction with the MCP registry follows a secure proxy pattern that separates data storage from model access.

The Proxy Endpoint

Rather than allowing the model to read raw registry entries, OpenWork funnels all MCP traffic through a scoped proxy endpoint:

/mcp/agent/connections/{connectionId}

This endpoint, implemented in apps/den-api/src/routes/mcp.ts, validates short-lived mcp:app-host credentials before forwarding requests. The model never receives the underlying provider descriptor; it only interacts with the abstracted capability layer.

The Search and Execution Flow

The model interacts with the registry through two discrete tools:

• search_capabilities – Queries the registry for available tools matching specific criteria, such as the mcp-app-host-v1 capability.
• execute_capability – Invokes a specific tool (for example, resources/read) with structured input, including metadata like _meta.ui.resourceUri.

These tools are defined in the registry abstraction layer (packages/openwork-mcp/src/registry.ts) and handle the translation between the model’s requests and the actual MCP server calls.

Source Code Implementation

The implementation spans multiple packages to enforce the security boundary between the registry and the model.

Documentation and Architecture

The canonical reference resides in docs/features/remote-mcp-apps/README.md. This file explains the rationale for avoiding direct registry writes and documents the io.modelcontextprotocol/ui extension protocol used to advertise UI-bound resources.

API Routing Layer

apps/den-api/src/routes/mcp.ts contains the HTTP handlers for the /mcp/agent/connections/{connectionId} endpoint. This route validates the App-host credential, extracts the connection scope, and proxies search_capabilities and execute_capability calls to the underlying MCP server without exposing the raw provider descriptor.

Registry Abstraction

packages/openwork-mcp/src/registry.ts defines how OpenWork reads the MCP provider index. It implements the logic for capability discovery while ensuring that only sanitized, proxy-bound references are returned to the model.

Client Credential Management

packages/openwork-mcp/src/client.ts handles the creation of the short-lived mcp:app-host credential. This credential grants bounded access to a specific connection ID, ensuring that even if the model's request is intercepted, it cannot access broader registry contents or provider internals.

Working With the Registry: Code Examples

Below are practical implementations showing how a model queries the OpenWork MCP registry and executes capabilities through the secure proxy.

Querying for UI-bound resources:

# Search the model-visible registry for MCP app capabilities

search_result = await tools.search_capabilities(
    query="ui.resourceUri",
    capability="mcp-app-host-v1"
)

# Returns sanitized tool definitions including name, input schema, and output schema

print(search_result)

Executing a specific capability:

# Invoke the resources/read tool through the proxy

tool_name = "resources/read"
resource_uri = "ui://my-app/resource.html"

result = await tools.execute_capability(
    capability=tool_name,
    input={
        "_meta": {
            "ui": {
                "resourceUri": resource_uri
            }
        }
    }
)

# Returns HTML content and structuredContent without exposing provider internals

print(result)

In these examples, the search_capabilities call targets only the model-visible subset of the registry, filtered by the mcp-app-host-v1 client capability. The execute_capability call routes through the private App-host credential, ensuring the request reaches the actual MCP server via the /mcp/agent/connections/{connectionId} proxy while keeping provider metadata confidential.

Summary

• The OpenWork MCP registry catalogs provider descriptors, tool schemas, and UI bindings for the OpenCode runtime.
• OpenWork deliberately avoids writing provider metadata directly to the model-visible registry, storing sensitive data in private App-host credentials instead.
• Models interact with capabilities via the search_capabilities and execute_capability tools, which serve as controlled interfaces to the underlying catalog.
• The /mcp/agent/connections/{connectionId} proxy endpoint enforces credential-scoped access, validating requests before forwarding them to MCP servers.
• Key implementation files include the documentation in docs/features/remote-mcp-apps/README.md, the API routes in apps/den-api/src/routes/mcp.ts, and the registry logic in packages/openwork-mcp/src/registry.ts.

Frequently Asked Questions

What is stored in the OpenWork MCP registry?

The registry stores provider descriptors for MCP servers, including tool definitions, resource schemas, input/output specifications, and UI binding metadata such as _meta.ui.resourceUri. These entries describe what capabilities are available but are kept separate from the actual provider implementation details visible to the model.

Why doesn't OpenWork write directly to the MCP registry?

OpenWork avoids direct registry writes as a security measure. By keeping provider-specific metadata in a private, non-public App-host credential rather than the model-visible registry, the system prevents the model from accessing sensitive configuration data or internal resource URIs that could expose system internals or create security vulnerabilities.

How does a model discover available MCP tools?

A model discovers tools by calling the search_capabilities tool with a specific capability filter, typically mcp-app-host-v1. This returns a sanitized list of available tools, their input schemas, and output schemas without revealing the underlying provider descriptors stored in the full OpenWork MCP registry.

What is the role of the connection proxy endpoint?

The /mcp/agent/connections/{connectionId} endpoint acts as a secure gateway. It validates the short-lived mcp:app-host credential, ensures the request is scoped to the specific connection, and forwards search_capabilities or execute_capability calls to the appropriate MCP server. This design prevents the model from directly accessing registry entries or provider infrastructure.

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