MCP Integration in Mako's Tool System: How External Tools Become First-Class Citizens

MCP (Maka Collaboration Protocol) integration enables Mako's runtime to discover, load, and execute external tools from remote MCP servers as if they were native capabilities.

MCP integration transforms Mako from a closed system into a pluggable platform where third-party services can extend functionality without touching core code. This deep dive explores how the apache/maka repository implements this protocol, from tool discovery through sandboxed execution.

How MCP Tool Discovery Works

The discovery phase begins when a client establishes a connection to an MCP server. The server publishes a catalog of tool definitions formatted as JSON Schema, which Mako consumes and validates.

In packages/mcp/src/tool-discovery.ts, the runtime fetches and parses these definitions:

// Tool discovery flow (conceptual usage)
import { discoverTools } from '@maka/mcp';

const tools = await discoverTools({ serverId: 'my-mcp' });
// Returns validated tool definitions with JSON Schema for arguments

Each definition undergoes strict validation in packages/mcp/src/tool-definition.ts, which enforces size limits and schema completeness. This prevents malformed or oversized tool definitions from entering the system.

The Uniform Tool Interface via MCP Proxies

Once discovered, every MCP tool gets wrapped as a proxy object in packages/runtime/src/mcp-tools.ts. This abstraction is critical—it lets the rest of Mako call external tools using identical patterns to native tools.

// Example: invoking an MCP-provided tool from a prompt
import { Runtime } from '@maka/runtime';

await Runtime.callTool({
  tool: { serverId: 'my-mcp', name: 'search' },
  arguments: { query: 'latest API docs' },
});

The proxy handles three responsibilities:

• Routing – Forwards calls to the correct MCP server
• Marshaling – Serializes arguments and deserializes results
• UI integration – Returns automatically clipped and serialized results for display

Security and Sandbox Boundaries

MCP integration does not bypass Mako's security model. Network access requested by MCP tools triggers sandbox-boundary validation with the explicit error message: MCP network access requires sandbox boundary approval.

The packages/runtime/src/mcp-tools.ts implementation enforces these checks before any remote execution occurs. Sessions must possess appropriate capabilities to grant network permissions, ensuring MCP tools operate within the same permission model as native tools.

Persistent MCP Configuration

Workspaces store MCP server credentials and connection parameters via packages/storage/src/mcp-config-store.ts:

// Example: adding a new MCP server to workspace config
import { McpConfigStore } from '@maka/storage';

await McpConfigStore.update({
  version: MCP_CONFIG_VERSION,
  mcpServers: {
    myMcp: {
      url: 'https://my-mcp.example.com',
      token: '***',
      protocol: 'json',
    },
  },
});

This dedicated config store provides:

• Per-workspace persistence – Servers attach to specific projects, not global installs
• Secure credential storage – Tokens are encrypted at rest
• Version migrations – Handles protocol evolution as MCP versions change

Extensibility Without Core Modifications

By exposing JSON Schema definitions, MCP enables third-party extensibility. Developers can add capabilities like code search, external API access, or domain-specific analysis without modifying Mako's core codebase.

The UI surfaces this through connection actions defined in packages/ui/src/tool-activity/copy.ts, making MCP server management accessible to end users.

Key Source Files for MCP Integration

File Path	Purpose
packages/mcp/src/tool-discovery.ts	Fetches and validates server-published tool catalogs
packages/mcp/src/tool-definition.ts	Enforces schema constraints and size limits on tool definitions
packages/runtime/src/mcp-tools.ts	Wraps MCP tools as proxies, enforces sandbox checks, handles argument/result marshaling
packages/storage/src/mcp-config-store.ts	Persists server configurations with secure credential handling
packages/ui/src/tool-activity/copy.ts	Exposes MCP connection actions in the user interface

Summary

• MCP integration bridges Mako's runtime with external tool servers through a standardized protocol
• tool-discovery.ts handles catalog fetching while tool-definition.ts validates schemas
• mcp-tools.ts proxy wrappers ensure external tools behave identically to native tools
• Sandbox boundaries protect against unauthorized network access from MCP-provided tools
• mcp-config-store.ts enables secure, workspace-scoped configuration persistence
• Third-party developers extend Mako by publishing JSON Schema tool definitions without core code changes

Frequently Asked Questions

What does MCP stand for in Mako?

MCP stands for Maka Collaboration Protocol. It is the communication standard that allows Mako's runtime to interact with external tool servers and treat their capabilities as native tools.

How does Mako validate tools from an MCP server?

Mako validates MCP tools through packages/mcp/src/tool-definition.ts, which checks JSON Schema completeness and enforces size limits on tool definitions before they enter the execution pipeline.

Can MCP tools access the network freely?

No. MCP tools are subject to the same sandbox boundary checks as native tools. The runtime explicitly requires MCP network access requires sandbox boundary approval before granting network capabilities.

Where are MCP server credentials stored?

Credentials are stored securely in packages/storage/src/mcp-config-store.ts, which provides per-workspace persistence, encryption at rest, and version migration support for evolving MCP protocol versions.

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