# How OpenWork Implements MCP Server Configuration and Server Name Validation

> OpenWork ensures MCP server configuration and validation with a three-layer system: JSON declarations, Zod schema for server names, and safety checks for URLs ending in /mcp/agent.

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

---

**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`](https://github.com/different-ai/openwork/blob/main/README.md), demonstrating how to expose an MCP endpoint within an [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) structure.

```json
{
  "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`](https://github.com/different-ai/openwork/blob/main/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.

```typescript
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`](https://github.com/different-ai/openwork/blob/main/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:

```typescript
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`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/domains/connections/mcp-connection-boundary.ts) creates user-friendly labels from plugin and server names:

```typescript
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:

```bash
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:

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

```

### Validating MCP URLs in TypeScript

```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

```tsx
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.