What Is the Model Context Protocol (MCP) in Maka?

The Model Context Protocol (MCP) is a provider-neutral protocol that exposes external tool connectors—from browser drivers to enterprise services—as native MakaTools through a unified execution boundary.

The Model Context Protocol (MCP) serves as the standard interface for integrating third-party capabilities into the Apache Maka agent runtime. Rather than implementing separate agent loops for external services, MCP allows remote tool definitions to be discovered, validated, and invoked through the same MakaTool execution model used for native functionality.

How MCP Integrates with the Maka Runtime

MCP bridges external capabilities by representing all remote tools as discriminated-union schemas that conform to the Tool type from @modelcontextprotocol/client. This design decision—implemented in packages/mcp/src/tool-definition.ts—ensures that whether a tool originates from a local module or a remote HTTP endpoint, it presents an identical interface to the Maka execution engine.

The integration avoids creating a secondary agent loop. Instead, MCP tools are dynamically injected into the local MakaTool array maintained by the runtime manager, allowing the existing execution boundary to handle invocation, telemetry, and abort logic without modification.

Schema Validation and Fingerprinting

Before any remote tool enters the execution context, Maka validates its definition through the fingerprintMcpToolDefinition function. This safety mechanism enforces strict resource guards:

• Maximum depth: 100 levels
• Maximum node count: 100,000 nodes
• Maximum byte size: 1 MiB

These limits prevent unbounded schema loading that would compromise runtime scalability. The validation logic resides in packages/mcp/src/tool-definition.ts, which analyzes the JSON schema structure to ensure compliance before registration proceeds.

Provider-Neutral Client Architecture

The packages/mcp directory contains a vendor-agnostic client capable of connecting to any MCP server regardless of transport mechanism. The createMcpClient factory function—exported from packages/mcp/src/index.ts—abstracts connection details for HTTP, stdio, and SSE transports while optionally handling OAuth 2.0 / PKCE authentication flows.

This provider-neutral design means Maka agents can consume tools from diverse sources—sub-agents, OS automation layers, or cloud services—without vendor-specific SDKs cluttering the codebase.

Runtime Discovery and Management

At the heart of the integration lies the MCP Manager, implemented in packages/mcp/src/manager.ts (with behavioral specifications detailed in the accompanying test suite at packages/mcp/src/__tests__/manager.test.ts). This component continuously discovers available MCP servers, caches their tool definitions, and refreshes metadata as endpoints update.

When the manager identifies new capabilities, it dynamically injects validated tool definitions into the runtime's active tool registry. This injection happens without restarting the agent, enabling hot-swapping of external capabilities during long-running sessions.

Security Model and Permissions

MCP tools inherit the identical permission model applied to native Maka tools, ensuring consistent access control across the entire tool surface. Additional metadata annotations guide runtime behavior:

• categoryHint: network_send triggers specific telemetry routing and plan-mode exclusion policies
• readOnlyHint serves as an advisory flag (non-enforcing) indicating the tool's intended access pattern

These security characteristics are documented in docs/architecture/mcp-runtime-architecture-draft.zh-CN.md, which outlines how MCP respects Maka's existing security boundaries while adding granular observability hints.

Implementing MCP Tools in Maka

The following pattern demonstrates connecting to an MCP server, validating remote definitions, and executing tools through the standard Maka runtime:

// 1️⃣ Import the MCP client and validation utilities
import { createMcpClient } from '@maka/mcp';
import { fingerprintMcpToolDefinition } from '@maka/mcp/src/tool-definition';
import type { Tool } from '@modelcontextprotocol/client';

// 2️⃣ Configure connection to an MCP server
const mcp = createMcpClient({
  endpoint: 'https://mcp.example.com/v1',
  auth: { apiKey: 'YOUR_API_KEY' }, // OAuth/PKCE supported
});

// 3️⃣ Discover and register remote tools
async function loadRemoteTools() {
  const remoteTools: Tool[] = await mcp.listTools();
  
  // Validate against depth, node, and size limits
  remoteTools.forEach(t => fingerprintMcpToolDefinition(t));
  
  // Inject into runtime (pseudo-API representation)
  MakaRuntime.registerTools(remoteTools);
}

// 4️⃣ Execute remote tools through standard interface
async function runRemoteTool() {
  const result = await MakaRuntime.runTool('webSearch', {
    query: 'Maka Model Context Protocol',
  });
  console.log('Search results →', result);
}

// Usage
loadRemoteTools().then(runRemoteTool).catch(console.error);

The fingerprintMcpToolDefinition call ensures that malicious or malformed schemas exceeding the 100-depth or 1-MiB limits are rejected before reaching the execution engine. Once registered via MakaRuntime.registerTools, remote MCP tools are indistinguishable from native tools when invoked through MakaRuntime.runTool.

Summary

• Unified Interface: MCP exposes external tools as native MakaTools through discriminated-union schemas defined in packages/mcp/src/tool-definition.ts.
• Resource Safety: Strict validation limits (100 depth, 100,000 nodes, 1 MiB) prevent schema-based denial-of-service attacks.
• Transport Agnostic: The createMcpClient factory supports HTTP, stdio, and SSE transports with built-in OAuth handling.
• Runtime Integration: The MCP Manager (src/manager.ts) handles dynamic discovery, caching, and hot-injection of remote capabilities.
• Inherited Security: MCP tools utilize the native permission model and support telemetry hints like categoryHint for fine-grained access control.

Frequently Asked Questions

What transport protocols does the MCP client support in Maka?

The MCP implementation in Apache Maka supports HTTP, stdio, and Server-Sent Events (SSE) transports. The createMcpClient function available in packages/mcp/src/index.ts abstracts transport specifics and optionally handles OAuth 2.0 or PKCE authentication flows, allowing connection to any compliant MCP server regardless of underlying protocol.

How does Maka prevent malicious or oversized MCP tool definitions?

Maka enforces resource guards through the fingerprintMcpToolDefinition function located in packages/mcp/src/tool-definition.ts. This validation layer rejects any schema exceeding 100 levels of depth, 100,000 total nodes, or 1 MiB in serialized size, preventing unbounded recursive structures from compromising runtime stability.

Do MCP tools inherit the same security controls as native Maka tools?

Yes. MCP tools operate under the identical permission model as native Maka tools, meaning they are subject to the same authorization checks and telemetry policies. Additionally, MCP-specific annotations like categoryHint: network_send provide metadata for plan-mode exclusion and routing decisions, while readOnlyHint serves as an advisory access indicator.

Which package contains the MCP implementation in the Apache Maka repository?

The complete MCP implementation resides in packages/mcp, with key entry points including packages/mcp/src/index.ts (public exports), packages/mcp/src/tool-definition.ts (schema validation), and packages/mcp/src/manager.ts (runtime discovery). Architectural documentation is available in docs/architecture/mcp-runtime-architecture-draft.zh-CN.md.

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