# What Is the OpenWork MCP Registry Used For?

> Discover how the OpenWork MCP registry catalogs Model Context Protocol providers for AI agent runtime tool discovery and invocation. Learn its role in OpenCode.

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

---

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

```python

# 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:

```python

# 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`](https://github.com/different-ai/openwork/blob/main/docs/features/remote-mcp-apps/README.md), the API routes in [`apps/den-api/src/routes/mcp.ts`](https://github.com/different-ai/openwork/blob/main/apps/den-api/src/routes/mcp.ts), and the registry logic in [`packages/openwork-mcp/src/registry.ts`](https://github.com/different-ai/openwork/blob/main/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.