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

> Discover the Model Context Protocol MCP in Maka, a provider-neutral protocol unifying external tool connectors as native MakaTools through a single execution boundary.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-08

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/mcp/src/manager.ts) (with behavioral specifications detailed in the accompanying test suite at [`packages/mcp/src/__tests__/manager.test.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/mcp/src/index.ts) (public exports), [`packages/mcp/src/tool-definition.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-definition.ts) (schema validation), and [`packages/mcp/src/manager.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/manager.ts) (runtime discovery). Architectural documentation is available in [`docs/architecture/mcp-runtime-architecture-draft.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/mcp-runtime-architecture-draft.zh-CN.md).