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

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, 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, 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 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 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. 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:

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

// 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.
• 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, 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—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.

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