Is There an Official OpenWork MCP Protocol Specification? Complete Technical Guide

OpenWork does not define a proprietary protocol; it implements the official Model Context Protocol (MCP) specification version 2025-11-25, an open-source JSON-RPC standard for client-server communication.

OpenWork leverages the Model Context Protocol (MCP) to enable standardized tool discovery and execution across enterprise environments. Unlike proprietary protocols, OpenWork's MCP implementation strictly follows the official specification published by the Model Context Protocol project. The OpenWork codebase enforces MCP 2025-11-25 compliance through specific transport layers, authorization flows, and strict lifecycle management.

Understanding the OpenWork MCP Protocol Specification

OpenWork does not invent its own communication protocol. Instead, the platform adopts the Model Context Protocol (MCP), an open-source, versioned standard maintained by the Model Context Protocol project.

The implementation follows MCP 2025-11-25, the latest stable release at the time of development. This specification defines:

• JSON-RPC message formatting
• Transport mechanisms including Streamable HTTP and stdio
• Authorization flows using OAuth 2.1
• Required HTTP headers including MCP-Protocol-Version and MCP-Session-Id

Official MCP Specification Resources

The canonical specification lives outside the OpenWork repository at the following URLs:

• Transport Layer: Streamable HTTP and stdio transport definitions at https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
• Authorization: OAuth 2.1-based MCP authorization at https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization

These documents prescribe the complete normative description of the protocol, including header requirements, message formats, and security constraints like PKCE and resource-bound tokens.

How OpenWork Implements the MCP Specification

The OpenWork codebase references the official MCP SDK and enforces specification compliance through several key components.

Transport Layer and Header Enforcement

In packages/enterprise-mcp-client/src/enterprise-mcp-client.ts, the enterprise MCP client constructs transports that inject the required MCP-Protocol-Version header. This file handles the complete MCP lifecycle from initialization to tool execution, ensuring every request conforms to the 2025-11-25 specification.

// Header enforcement as implemented in enterprise-mcp-client.ts
const headers = {
  'MCP-Protocol-Version': '2025-11-25',
  'MCP-Session-Id': sessionId,
};

UI Integration with MCP SDK

The UI layer imports standard MCP SDK components directly from the official package. According to docs/mcp-ui-control-profile.md, OpenWork imports Client and StdioClientTransport from @modelcontextprotocol/sdk to bridge the user interface with protocol-compliant transports.

Type Definitions and JSON-RPC Modeling

The packages/enterprise-mcp-client/src/contracts.ts file contains TypeScript definitions that model the MCP JSON-RPC request and response shapes. These type definitions enforce the correct structure for initialization parameters, tool listings, and execution results according to the official specification.

Spec Conformance Declaration

The docs/enterprise-mock-lab.md documentation explicitly marks OpenWork's implementation as spec-conformant, linking directly to the official MCP transport and authorization specifications. This ensures that any mock servers or test environments validate against the same standard used in production.

MCP Protocol Lifecycle in OpenWork

OpenWork strictly follows the four-phase MCP lifecycle defined in the specification:

1. Initialize: Client sends initialize request with protocol version and capabilities
2. Initialized: Server acknowledges with supported features and protocol version alignment
3. Tool Discovery: Client requests available tools via listTools JSON-RPC method
4. Tool Execution: Client invokes specific tools via callTool with proper argument validation

Each phase validates the MCP-Protocol-Version header and maintains session continuity through MCP-Session-Id management.

Practical Implementation Examples

The following TypeScript examples demonstrate how OpenWork interacts with the official MCP specification using the enterprise client.

Creating an Enterprise MCP Client

import { createEnterpriseMcpClient } from '@openwork/enterprise-mcp-client';
import type {
  EnterpriseMcpConnection,
  EnterpriseMcpConnectInput,
} from '@openwork/enterprise-mcp-client/contracts';

const connection: EnterpriseMcpConnection = {
  id: 'my-org-mcp',
  serverUrl: 'https://api.openworklabs.com/mcp/agent',
  authorization: {
    type: 'oauth',
    persistence: {/* configuration */},
  },
};

const mcpClient = createEnterpriseMcpClient({
  clientName: 'MyOpenWorkApp',
  clientVersion: '1.2.3',
});

async function connectMcp() {
  const input: EnterpriseMcpConnectInput = {
    connection,
    redirectUri: 'http://localhost:3000/callback',
  };

  const result = await mcpClient.connect(input);
  if (result.status === 'needs_auth') {
    console.log('Authorize here:', result.authorizeUrl);
  } else {
    console.log('MCP connection established');
  }
}

This constructor uses the spec-defined transport and automatically handles the MCP-Protocol-Version header during the initialization phase.

Discovering Available Tools

import type { EnterpriseMcpListToolsInput } from '@openwork/enterprise-mcp-client/contracts';

async function listTools() {
  const input: EnterpriseMcpListToolsInput = {
    connection,
    redirectUri: 'http://localhost:3000/callback',
  };

  const tools = await mcpClient.listTools(input);
  console.log('Available MCP tools:', tools.map(t => t.name));
}

The listTools method follows the MCP specification by issuing a JSON-RPC request to the server's /listTools endpoint and parsing the paginated response.

Invoking MCP Tools

import type { EnterpriseMcpCallToolInput } from '@openwork/enterprise-mcp-client/contracts';

async function runTool(toolName: string, args: Record<string, unknown>) {
  const input: EnterpriseMcpCallToolInput = {
    connection,
    redirectUri: 'http://localhost:3000/callback',
    toolName,
    arguments: args,
  };

  const result = await mcpClient.callTool(input);
  console.log('Tool result:', result);
}

This executes the tool according to the MCP JSON-RPC callTool method, maintaining protocol compliance through proper message formatting and header management.

Summary

• OpenWork implements the Model Context Protocol (MCP) 2025-11-25 specification rather than defining a proprietary protocol
• The official specification resides at modelcontextprotocol.io and covers transport layers, authorization, and JSON-RPC message formats
• Key implementation files include packages/enterprise-mcp-client/src/enterprise-mcp-client.ts for transport handling and docs/mcp-ui-control-profile.md for SDK integration
• The protocol enforces strict header requirements including MCP-Protocol-Version and MCP-Session-Id
• OpenWork supports the complete MCP lifecycle: initialize → initialized → tool discovery → tool execution

Frequently Asked Questions

Does OpenWork use a custom MCP protocol?

No. OpenWork adopts the official Model Context Protocol (MCP) maintained by the Model Context Protocol project. The implementation follows the open-source, versioned standard for JSON-RPC client-server communication rather than a proprietary protocol.

What version of the MCP specification does OpenWork support?

OpenWork implements MCP 2025-11-25, which was the latest stable version at the time of writing. The codebase enforces this version through the MCP-Protocol-Version header in packages/enterprise-mcp-client/src/enterprise-mcp-client.ts.

Where can I find the official MCP transport specification?

The official transport layer specification, including Streamable HTTP and stdio definitions, is available at https://modelcontextprotocol.io/specification/2025-11-25/basic/transports. OpenWork references this documentation in docs/enterprise-mock-lab.md to ensure spec conformance.

How does OpenWork handle MCP authorization?

OpenWork follows the OAuth 2.1-based authorization flow defined in the MCP specification at https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. This includes support for resource-bound tokens, PKCE, and scope handling as implemented in the enterprise client connection logic.

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