# Architecture of the Remote MCP Gateway at api.openworklabs.com/mcp/agent

> Explore the architecture of the remote MCP gateway at api.openworklabs.com/mcp/agent. Learn how this Hono-based entry point securely authenticates AI agents and dispatches requests.

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

---

**The remote MCP gateway at api.openworklabs.com/mcp/agent is a stateless Hono-based HTTP entry point that authenticates AI agents via signed JWTs and dispatches capability discovery and execution requests to internal microservices.**

The `different-ai/openwork` repository implements this Model-Control-Plane (MCP) gateway in the `ee/apps/den-gateway` package. It serves as the public façade for the Open Work platform, exposing a language-agnostic API that allows client-side agents to discover available capabilities and invoke them securely without direct access to underlying infrastructure.

## HTTP Server and Application Bootstrap

The gateway lifecycle begins in **[`ee/apps/den-gateway/src/server.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-gateway/src/server.ts)**, which boots a Node.js HTTP server and mounts the Hono application framework. Upon successful startup, the server emits a structured JSON log message indicating readiness, enabling observability systems to detect healthy instances immediately.

Application logic resides in **[`ee/apps/den-gateway/src/app.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-gateway/src/app.ts)**, where the Hono instance registers global middleware and route handlers. This file orchestrates CORS configuration, JSON body parsing, and the middleware chain that every request traverses before reaching capability-specific logic.

## Environment Configuration and Validation

Runtime configuration is strictly environment-driven. The **[`ee/apps/den-gateway/src/env.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-gateway/src/env.ts)** module defines the schema for required variables—including the server port, JWT signing secrets, and allowed CORS origins—and validates them at startup. For local development, **[`ee/apps/den-gateway/src/load-env.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-gateway/src/load-env.ts)** parses `.env` files to inject these values. If validation fails, the process exits immediately to prevent serving traffic with incomplete security settings.

## Authentication and Security Model

Security is enforced through an inline `auth` middleware function defined in [`app.ts`](https://github.com/different-ai/openwork/blob/main/app.ts). Each incoming request must present a valid JWT in the `Authorization: Bearer <token>` header. The gateway verifies the token signature and decodes claims that encode the **client-ID**, an array of permitted **capabilities**, and an expiration timestamp. Requests with missing, malformed, or expired tokens receive an immediate `401` response without touching downstream services.

## Capability Dispatch Architecture

The gateway exposes two primary MCP protocol endpoints implemented as handler functions in [`app.ts`](https://github.com/different-ai/openwork/blob/main/app.ts):

- **`searchCapabilitiesHandler`** – Handles `POST /search_capabilities` requests. It returns a JSON list of capabilities the authenticated client is authorized to invoke, filtered by the JWT claims.
- **`executeCapabilityHandler`** – Handles `POST /execute_capability` requests. It validates that the requested capability exists in the client’s permitted list, then forwards the payload to the appropriate internal service—typically the `den-api` peer service—and streams the response back to the caller.

This dispatch pattern keeps the gateway stateless; itdoes not cache request data or maintain session state between calls. All mutable context exists solely within the JWT claims and temporary request-scoped objects.

## Rate Limiting, Telemetry, and Error Handling

Per-client usage tracking and quota enforcement are implemented within [`app.ts`](https://github.com/different-ai/openwork/blob/main/app.ts) and exercised in **`ee/apps/den-gateway/test/gateway.test.mjs`**. The test suite validates end-to-end authentication flows, capability invocation, and rate-limiting behavior.

Centralized error normalization occurs at the end of the Hono middleware chain via an `errorHandler` that converts internal exceptions into the standardized MCP-protocol error format (`{error: …}`). This ensures AI agents receive predictable error structures regardless of which internal service generated the failure.

## How Clients Call the Gateway

Clients interact with the HTTPS endpoint using standard HTTP POST requests. The following examples demonstrate capability discovery and invocation:

```javascript
// Discover available capabilities
const capabilities = await fetch('https://api.openworklabs.com/mcp/agent/search_capabilities', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${myJwt}`
  },
  body: JSON.stringify({ client_id: 'my-client' })
});

// Execute a specific capability (e.g., code completion)
const result = await fetch('https://api.openworklabs.com/mcp/agent/execute_capability', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${myJwt}`
  },
  body: JSON.stringify({
    capability: 'openai/completion',
    input: { prompt: 'Write a short poem about sunrise.' }
  })
});

```

The JWT must include a `capabilities` claim array listing the specific capabilities the client is allowed to execute. The gateway validates this claim before forwarding any `execute_capability` request to the backend.

## Integration with Internal Services

While the gateway handles protocol translation and authentication, it delegates business logic to specialized internal services:

- **`den-api`** (located in `ee/apps/den-api`) implements the actual capability logic, such as OpenAI API calls or plugin execution. The gateway treats this as a peer service, forwarding validated payloads and streaming responses.
- **`den-controller`** (located in `ee/apps/den-controller`) manages plugin registration, marketplace synchronization, and organization-wide policy enforcement. The gateway relies on this service for upstream permission checks and capability registry updates.

TLS termination occurs at the deployment environment level (e.g., load balancer or reverse proxy), ensuring all traffic reaching the gateway is encrypted while keeping the Node.js application simple and unprivileged.

## Summary

- The gateway is implemented in **`ee/apps/den-gateway`** using the lightweight **Hono** framework for Node.js.
- **Authentication** relies on signed JWTs containing capability claims, enforced by middleware in [`app.ts`](https://github.com/different-ai/openwork/blob/main/app.ts).
- Two primary endpoints— **`/search_capabilities`** and **`/execute_capability`**—handle discovery and invocation respectively.
- The architecture is **stateless**, with no session persistence between requests; authorization is derived entirely from JWT claims.
- **Internal delegation** forwards execution requests to the `den-api` service, while `den-controller` manages upstream policy.
- **Comprehensive testing** in `gateway.test.mjs` validates authentication, routing, and rate-limiting logic.

## Frequently Asked Questions

### What is the MCP protocol used by api.openworklabs.com/mcp/agent?

The MCP (Model-Control-Plane) protocol is a JSON-based HTTP API that allows AI agents to discover and invoke capabilities exposed by an Open Work installation. According to the `different-ai/openwork` source code, it specifies two primary operations: `search_capabilities` for discovery and `execute_capability` for invocation, both authenticated via JWT bearer tokens.

### How does the gateway validate client permissions?

The gateway validates permissions by inspecting the `capabilities` claim inside the decoded JWT. Implemented in the `auth` middleware within [`ee/apps/den-gateway/src/app.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-gateway/src/app.ts), this validation ensures that the capability requested in an `execute_capability` call appears in the client’s allowed list. If the claim is missing or the capability is not listed, the gateway returns a `401` or `403` response before forwarding the request to backend services.

### Is the remote MCP gateway stateless?

Yes, the gateway is fully stateless. As implemented in `ee/apps/den-gateway`, it maintains no server-side session storage or request history between calls. All authorization context is carried in the JWT claims, and all mutable data interactions are delegated to the `den-api` or `den-controller` services. This design allows the gateway to scale horizontally by simply adding more instances behind a load balancer.

### What happens when a capability execution fails?

When an internal service returns an error, the gateway’s centralized `errorHandler` middleware—located at the end of the Hono chain in [`ee/apps/den-gateway/src/app.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-gateway/src/app.ts)—normalizes the exception into the MCP-protocol error format (`{error: …}`). This ensures that client agents receive consistent, parseable error structures regardless of whether the failure originated in the gateway, the `den-api` service, or a downstream plugin.