{"record":{"id":"ca5bc15a97a5f2fd","repo":"different-ai/openwork","slug":"mcp-catalog-tool-name-limit","errorCode":"MCP_CATALOG_TOOL_NAME_LIMIT","errorMessage":"MCP_CATALOG_TOOL_NAME_LIMIT","messagePattern":"MCP_CATALOG_TOOL_NAME_LIMIT","errorType":"error_code","errorClass":"ExternalMcpDiagnosticError","httpStatus":null,"severity":"warning","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-client.ts","lineNumber":626,"sourceCode":"  const operatorAction = measurement.reason === \"depth\"\n    ? `Flatten each tool schema below ${EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT} nested levels.`\n    : measurement.reason === \"cycle\"\n      ? \"Return JSON-serializable, acyclic tool schemas.\"\n      : `Reduce each serialized tool schema below ${EXTERNAL_MCP_TOOL_SCHEMA_LIMIT_BYTES} bytes.`\n  throw catalogDiagnosticError({ tracker: input.diagnostic, code, operatorAction })\n}\n\nfunction measureCatalogTool(input: {\n  diagnostic: ExternalMcpDiagnosticTracker\n  tool: ExternalMcpToolPage[\"tools\"][number]\n  remainingBytes: number\n}): number {\n  validateToolCatalogField({\n    diagnostic: input.diagnostic,\n    value: input.tool.name,\n    field: \"name\",\n    limit: EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES,\n    code: \"MCP_CATALOG_TOOL_NAME_LIMIT\",\n  })\n  validateToolCatalogField({\n    diagnostic: input.diagnostic,\n    value: input.tool.title,\n    field: \"title\",\n    limit: EXTERNAL_MCP_TOOL_TITLE_LIMIT_BYTES,\n    code: \"MCP_CATALOG_TOOL_TITLE_LIMIT\",\n  })\n  validateToolCatalogField({\n    diagnostic: input.diagnostic,\n    value: input.tool.description,\n    field: \"description\",\n    limit: EXTERNAL_MCP_TOOL_DESCRIPTION_LIMIT_BYTES,\n    code: \"MCP_CATALOG_TOOL_DESCRIPTION_LIMIT\",\n  })\n  validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.inputSchema })\n  if (input.tool.outputSchema !== undefined) {\n    validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.outputSchema })","sourceCodeStart":608,"sourceCodeEnd":644,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-client.ts#L608-L644","documentation":"External MCP tool catalog validation: each tool's `name` field is checked against EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES using validateToolCatalogField. A tool whose name exceeds the byte limit produces diagnostic code MCP_CATALOG_TOOL_NAME_LIMIT, rejecting that tool (or the catalog sync) rather than accepting oversized identifiers that break downstream storage/routing.","triggerScenarios":"Syncing/publishing an external MCP server whose tool definition has a name longer than the configured byte limit — typically very long namespaced tool names like my_org__very_long_integration__do_something_specific_v2.","commonSituations":"Upstream MCP server generating verbose tool names; concatenating server prefix + tool name before publishing; migration from another gateway that allowed longer names; multibyte characters consuming bytes faster than characters.","solutions":["Shorten the tool name on the external MCP server so it fits within EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES.","Check the diagnostic payload for the exact byte count vs. limit, then trim the namespacing/prefix.","If the upstream name can't change, register an alias/mapping with a short name at the gateway level.","If the limit is too strict for your org, adjust EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES in the Den API config."],"exampleFix":"// before\nserver.tool(\"acme_corporate_crm_integration_create_contact_record_v2\", ...)\n// after\nserver.tool(\"acme_create_contact\", ...)","handlingStrategy":"validation","validationCode":"const LIMIT = 128; // keep in sync with EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES\nnew TextEncoder().encode(tool.name).length <= LIMIT || reject(tool, \"tool name exceeds byte limit\");","typeGuard":null,"tryCatchPattern":"try {\n  await syncCatalog(source);\n} catch (e) {\n  if (e.diagnostics?.some((d) => d.code === \"MCP_CATALOG_TOOL_NAME_LIMIT\")) {\n    // skip/alias the offending tool instead of failing the whole sync\n  } else throw e;\n}","preventionTips":["Enforce short, namespaced tool naming conventions on upstream MCP servers","Count bytes, not characters, when checking name lengths","Run catalog validation in CI before publishing external servers"],"tags":["validation","mcp","catalog","limits"],"backgroundTag":"field-length-limit-exceeded","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}