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

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 (as documented in packages/docs/model-context-protocol/opencode.mdx):

{
  "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:

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

This returns a JSON array of matching capabilities:

{
  "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:

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:

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 (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 — 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 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), 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 around line 687. Type definitions for connection actions reside in 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.

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