How OpenWork Implements MCP Server Configuration and Server Name Validation

OpenWork validates MCP server configurations through a three-layer system: JSON-based remote server declarations, Zod schema validation for server names (trimmed, 1-255 characters), and safety checks ensuring URLs end with /mcp/agent without unsafe characters.

The different-ai/openwork repository provides a robust implementation for managing Model Context Protocol (MCP) servers across its ecosystem. Understanding how this platform handles MCP server configuration and server name validation reveals a type-safe pipeline designed for security and consistency. The implementation spans from client-side JSON configuration files to strict API-level schema enforcement.

Declaring Remote MCP Servers in Configuration

OpenWork enables developers to register remote MCP servers through standard JSON configuration files consumed by compatible clients. The recommended setup appears in the repository's README.md, demonstrating how to expose an MCP endpoint within an opencode.json structure.

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

The type: "remote" designation signals that the MCP operates over HTTP rather than local execution. The url field must target a valid MCP protocol endpoint, specifically requiring the /mcp/agent path suffix enforced by backend validation rules.

Server Name Schema Validation with Zod

When users configure MCP requirements for plugins, OpenWork validates the serverName parameter using the pluginMcpRequirementConfigureSchema defined in ee/apps/den-api/src/routes/org/plugin-system/schemas.ts. This Zod schema enforces strict constraints to prevent malformed data from entering the database.

export const pluginMcpRequirementConfigureSchema = z.object({
  configObjectId: configObjectIdSchema,
  serverName: z.string().trim().min(1).max(255),   // strict validation
  authType: z.enum(["oauth", "apikey", "none"]).optional().default("oauth"),
  credentialMode: z.enum(["shared", "per_member"]).optional(),
  apiKey: z.string().trim().min(1).max(4096).optional(),
  oauthClient: z.object({
    clientId: z.string().trim().min(1).max(512),
    clientSecret: z.string().trim().min(1).max(4096).optional(),
  }).optional(),
});

The validation chain performs three critical operations on the server name:

• trim() removes leading and trailing whitespace
• min(1) prevents empty string submissions
• max(255) aligns with the database varchar(255) column constraint

Failed validation immediately returns a 400 Bad Request with specific path-based error messages, blocking empty or oversized server names before they reach the datastore.

MCP Path Safety and Connection Naming

OpenWork implements additional safety mechanisms in packages/types/src/agent-context-diagnostics.ts to validate URL structures and generate human-readable connection identifiers.

URL Path Validation

The isCloudMcpPathSafe function ensures cloud MCP paths conform to strict security requirements:

function isCloudMcpPathSafe(value: string): boolean {
  return !forbiddenDiagnosticTextPattern.test(value)            // no control chars
    && diagnosticCloudMcpPathPattern.test(value)               // must match “…/mcp/agent”
    && !value.endsWith("/mcp/agent/");                         // no trailing slash
}

The underlying regex pattern /^\/(?:[^?#\u0000-\u001f\u007f-\u009f]+\/)*mcp\/agent$/u enforces that URLs:

• End exactly with /mcp/agent
• Contain no query strings or hash fragments
• Exclude forbidden control characters (U+0000-U+001F, U+007F-U+009F)

Display Name Construction

The externalMcpConnectionName function in apps/app/src/react-app/domains/connections/mcp-connection-boundary.ts creates user-friendly labels from plugin and server names:

function externalMcpConnectionName(input: { pluginName: string; serverName: string }) {
  const serverName = input.serverName.trim();
  if (!pluginName) return serverName || "Imported MCP";
  if (!serverName) return pluginName;
  return `${pluginName} / ${serverName}`;
}

This helper trims whitespace and provides fallback logic, ensuring the UI remains tolerant to incomplete data while the backend maintains strict validation.

Practical Implementation Examples

Creating an MCP Requirement via API

The following curl command demonstrates how to register an MCP server with validated parameters:

curl -X POST https://api.openworklabs.com/den/v1/org/123/plugin/456/mcp-requirement \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "configObjectId": "conf-abc",
        "serverName": "openwork-cloud",
        "authType": "oauth",
        "credentialMode": "shared"
      }'

If the serverName violates constraints (empty or >255 characters), the API responds with:

{
  "error": "Invalid input",
  "details": [{ "path": ["serverName"], "message": "String must contain at least 1 character(s)" }]
}

Validating MCP URLs in TypeScript

import { cloudMcpPathSchema } from "./agent-context-diagnostics";

const validUrl = "https://api.openworklabs.com/mcp/agent";
cloudMcpPathSchema.parse(validUrl);   // ✅ passes

const invalidUrl = "https://api.openworklabs.com/mcp/agent?token=abc";
cloudMcpPathSchema.parse(invalidUrl); // ❌ throws validation error

Rendering Connection Labels in React

import { externalMcpConnectionName } from "./mcp-connection-boundary";

const label = externalMcpConnectionName({ 
  pluginName: "Slack", 
  serverName: "openwork-cloud" 
});
// Result: "Slack / openwork-cloud"

Summary

OpenWork's MCP server configuration system combines client-side declarations with rigorous backend validation:

• Configuration files (opencode.json) define remote MCP servers with required URL endpoints
• Zod schemas (pluginMcpRequirementConfigureSchema) enforce server name constraints (trimmed, 1-255 characters) at the API layer
• Path validation (isCloudMcpPathSafe) guarantees MCP URLs end with /mcp/agent and contain no unsafe characters
• Display helpers (externalMcpConnectionName) generate consistent UI labels while handling edge cases
• Type safety throughout the TypeScript codebase prevents malformed data from reaching the database

Frequently Asked Questions

What is the maximum length for an MCP server name in OpenWork?

OpenWork limits MCP server names to 255 characters, matching the database varchar(255) column specification. The pluginMcpRequirementConfigureSchema in ee/apps/den-api/src/routes/org/plugin-system/schemas.ts enforces this through Zod's max(255) validator, immediately rejecting oversized names with a validation error.

Why must MCP URLs end with /mcp/agent?

The /mcp/agent suffix serves as a standardized endpoint identifier for the Model Context Protocol implementation. The isCloudMcpPathSafe function and cloudMcpPathSchema in packages/types/src/agent-context-diagnostics.ts enforce this pattern to ensure consistent routing and prevent misconfigured endpoints from connecting to the platform.

How does OpenWork handle whitespace in server names?

The platform automatically trims whitespace using Zod's trim() method during API validation, then applies min(1) to reject empty strings. The externalMcpConnectionName function performs additional trimming when generating display labels, ensuring no leading or trailing spaces appear in the user interface or database records.

Can users submit MCP configurations with query parameters in the URL?

No. The validation regex in diagnosticCloudMcpPathPattern explicitly forbids query strings (?), hash fragments (#), and control characters. The isCloudMcpPathSafe function returns false for any URL containing these elements, preventing potential injection attacks or routing errors in the MCP connection handler.

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