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

> Discover how MCP integration in Mako transforms external tools into first-class citizens. Load and execute remote tools seamlessly within Mako's runtime.

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

---

**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`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-discovery.ts), the runtime fetches and parses these definitions:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/mcp-config-store.ts):

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-discovery.ts) | Fetches and validates server-published tool catalogs |
| [`packages/mcp/src/tool-definition.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/tool-definition.ts) | Enforces schema constraints and size limits on tool definitions |
| [`packages/runtime/src/mcp-tools.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/mcp-config-store.ts) | Persists server configurations with secure credential handling |
| [`packages/ui/src/tool-activity/copy.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/tool-discovery.ts)** handles catalog fetching while **[`tool-definition.ts`](https://github.com/apache/maka/blob/main/tool-definition.ts)** validates schemas
- **[`mcp-tools.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/mcp-config-store.ts), which provides per-workspace persistence, encryption at rest, and version migration support for evolving MCP protocol versions.