# MCP Gateway Tools in OpenWork: A Complete Guide to the Two-Tool Architecture

> Explore OpenWork's MCP Gateway tools, search_capabilities and execute_capability. Discover and invoke organizational capabilities via a single remote endpoint with this comprehensive guide.

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

---

**OpenWork's MCP Gateway exposes exactly two tools—`search_capabilities` and `execute_capability`—through a single remote endpoint at `https://api.openworklabs.com/mcp/agent`, enabling any Model Context Protocol (MCP) compatible client to discover and invoke organizational capabilities.**

The **MCP Gateway** in the `different-ai/openwork` repository provides a unified interface for AI agents to access organizational resources. Unlike traditional MCP implementations that expose dozens of individual tools, OpenWork uses a minimal surface area approach. All organizational features—including skills, plugins, connectors, and collections—are accessed through just two stable tool definitions, simplifying integration with clients like OpenCode, Codex, Claude Code, Cursor, and VS Code.

## The Two MCP Gateway Tools

According to the source code in `packages/docs/cloud/run-in-the-cloud/cloud-mcp.mdx`, the gateway exposes only two public tools. This design choice replaces the older "many-tool" model with a stable contract that never changes, even as organizational capabilities grow.

### search_capabilities

The `search_capabilities` tool queries the catalog of capabilities available to the authenticated member. It accepts a JSON-RPC request with optional parameters and returns matching capability definitions.

**Key parameters:**
- `query` — Optional search string to filter capabilities
- `limit` — Maximum number of results to return
- `type` — Filter by capability type (skills, plugins, connectors, etc.)

The server returns capability definitions including the tool name, description, and UI metadata required for client rendering.

### execute_capability

The `execute_capability` tool runs a specific capability discovered through `search_capabilities`. It requires the exact capability name returned by the search operation along with any required input arguments.

When invoked, the server executes the underlying operation—such as creating a skill, invoking a connector, or managing collections—and returns either the execution result or an MCP App UI payload for client-side rendering.

## How to Connect to the MCP Gateway

All MCP-enabled clients connect to the same remote endpoint. Authentication occurs via OAuth, returning a token scoped to the selected organization. Subsequent calls to `search_capabilities` and `execute_capability` use this token for authorization.

Add the following configuration to your OpenCode [`settings.json`](https://github.com/different-ai/openwork/blob/main/settings.json) (as documented in `packages/docs/model-context-protocol/opencode.mdx`):

```json
{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}

```

The gateway internally expands requests into the full catalog of organization-wide resources, but clients only ever interact with the two tool names.

## Practical Usage Examples

The typical client pattern follows a **search → pick → execute** workflow. Below are implementation examples using the OpenCode CLI and TypeScript.

### Searching for Capabilities

To find available Google Drive operations:

```bash
opencode mcp call openwork search_capabilities '{"query":"drive","limit":5}'

```

This returns a JSON array of matching capabilities:

```json
{
  "results": [
    {
      "name": "openwork-google_drive_list_files",
      "description": "List files in Google Drive"
    }
  ]
}

```

### Executing a Capability

Once you identify the capability name, invoke it with the required input parameters:

```bash
opencode mcp call openwork execute_capability '{
  "name":"openwork-google_drive_list_files",
  "input":{"folderId":"root","pageSize":10}
}'

```

The response contains either the tool's output data or an MCP App UI payload that the client can render.

### Full Integration Script

For programmatic access in Node.js or TypeScript environments:

```typescript
import { execSync } from "child_process";

// 1️⃣ Search capabilities
const search = execSync(
  `opencode mcp call openwork search_capabilities '{"query":"skill","limit":3}'`,
  { encoding: "utf8" }
);
const { results } = JSON.parse(search);
const skillTool = results.find((c: any) => c.name.includes("create_skill"));

// 2️⃣ Execute the chosen capability
const exec = execSync(
  `opencode mcp call openwork execute_capability '${JSON.stringify({
    name: skillTool.name,
    input: { name: "DailyReport", description: "Generates a status report" },
  })}'`,
  { encoding: "utf8" }
);
console.log("Execution result:", exec);

```

This script demonstrates the canonical interaction pattern: search for capabilities, select the appropriate tool by name, then execute with structured input.

## Architecture and Implementation Details

The gateway implementation spans several key files in the `different-ai/openwork` repository:

- **`packages/docs/cloud/run-in-the-cloud/cloud-mcp.mdx`** — Documents the public contract and the two-tool architecture
- **[`apps/server/src/local-managed-mcp.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/local-managed-mcp.ts)** (around line 687) — Contains the internal registration of the "OpenWork Local MCP Gateway" and the exposure of `search_capabilities` and `execute_capability`
- **[`packages/types/src/den/mcp-connection-action.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/mcp-connection-action.ts)** — Defines the TypeScript schema for gateway actions, including retry mechanisms for `search_capabilities` requests
- **`evals/specs/**/opencode-mcp-agent-oauth.e2e.test.ts`** — End-to-end tests confirming the gateway returns exactly the two specified tools and handles OAuth authentication correctly
- **`packages/docs/model-context-protocol/*.mdx`** — Client-specific integration guides for OpenCode, Codex, Cursor, and other MCP clients

The gateway's minimalist approach ensures backward compatibility. As new capabilities are added to an organization, they appear in `search_capabilities` results without requiring client updates or changes to the tool definitions.

## Summary

- OpenWork's MCP Gateway uses a **two-tool architecture** consisting of `search_capabilities` and `execute_capability`
- All clients connect to **`https://api.openworklabs.com/mcp/agent`** using OAuth authentication
- The **search → pick → execute** workflow enables dynamic discovery of organizational resources without hardcoding tool definitions
- Source files in `packages/docs/cloud/run-in-the-cloud/cloud-mcp.mdx` and [`apps/server/src/local-managed-mcp.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/local-managed-mcp.ts) define the public contract and internal implementation
- This design provides a stable, future-proof interface that supports unlimited organizational capabilities through a minimal API surface

## Frequently Asked Questions

### What are the MCP Gateway tools in OpenWork?

OpenWork's MCP Gateway exposes exactly two tools: `search_capabilities` and `execute_capability`. The `search_capabilities` tool queries available organizational resources (skills, plugins, connectors) while `execute_capability` runs the selected operation with provided arguments. This two-tool architecture replaces the traditional approach of exposing dozens of individual tools to MCP clients.

### How do I authenticate with the OpenWork MCP Gateway?

Authentication occurs via OAuth when configuring the MCP client. In your client configuration (such as OpenCode's [`settings.json`](https://github.com/different-ai/openwork/blob/main/settings.json)), you specify the gateway URL `https://api.openworklabs.com/mcp/agent` with an `oauth` configuration object. Upon connection, the client receives a token scoped to your chosen organization, which authorizes all subsequent `search_capabilities` and `execute_capability` calls.

### What URL endpoint do I use to connect to the MCP Gateway?

All MCP-compatible clients connect to `https://api.openworklabs.com/mcp/agent`. This single endpoint handles requests for all organizational capabilities. According to the source code in `packages/docs/cloud/run-in-the-cloud/cloud-mcp.mdx`, this URL remains constant regardless of which specific capabilities you intend to use or which client (OpenCode, Codex, Claude Code, Cursor, VS Code) initiates the connection.

### Where is the MCP Gateway implementation defined in the source code?

The gateway architecture is primarily defined in `packages/docs/cloud/run-in-the-cloud/cloud-mcp.mdx` for the public contract, with the internal tool registration occurring in [`apps/server/src/local-managed-mcp.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/local-managed-mcp.ts) around line 687. Type definitions for connection actions reside in [`packages/types/src/den/mcp-connection-action.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/mcp-connection-action.ts), and end-to-end validation tests are located in `evals/specs/**/opencode-mcp-agent-oauth.e2e.test.ts`.