How Apache Maka Discovers and Loads MCP Servers: A Complete Technical Guide

Maka discovers MCP servers by reading mcp-config.json through McpConfigStore, resolves transport protocols via resolveMcpProtocolPreference, and loads tool definitions through the ToolDiscovery pipeline before registering them as scoped runtime capabilities with RuntimeHost.

Apache Maka treats each MCP (Model-Controlled Platform) server as a first-class tool provider within its ecosystem. The discovery and loading process involves a multi-stage pipeline that locates server configurations, negotiates transport protocols, validates tool schemas, and exposes capabilities to the runtime environment. This architecture enables dynamic addition or removal of MCP servers without requiring application restarts.

Step 1: MCP Configuration Loading and Protocol Resolution

The discovery process begins with persistent configuration storage. Maka maintains a JSON configuration file named mcp-config.json in the user's settings directory, managed by the McpConfigStore class.

Reading mcp-config.json with McpConfigStore

Located in packages/storage/src/mcp-config-store.ts, the McpConfigStore persists the list of server IDs and their corresponding HTTP endpoints. The configuration store handles file I/O operations and ensures JSON schema validation before returning configuration objects to the discovery pipeline. When the application initializes, this store reads the persisted server list to determine which MCP endpoints to contact.

Resolving Transport Protocol Preferences

Each server entry specifies a preferred protocol—http, https, ws, or wss. The helper function resolveMcpProtocolPreference, exported from @maka/core/mcp and implemented in packages/mcp/src/index.ts, selects the most secure protocol supported by the client environment. This ensures encrypted WebSocket (wss) or HTTPS connections are prioritized over unencrypted alternatives.

Step 2: Connection Establishment and Tool Discovery

Once configurations are resolved, Maka establishes persistent communication channels to each registered server.

Instantiating the MCP Manager

The McpManager class, defined in packages/mcp/src/manager.ts, coordinates server connections. Upon initialization, it opens either STDIO or WebSocket channels to each endpoint and negotiates server capabilities, such as support for tool definition streaming. The manager maintains these connections throughout the application lifecycle and handles reconnection logic when networks fluctuate.

Paginated Tool Discovery via ToolDiscovery

The actual tool enumeration occurs through discoverMcpTools(serverId), which utilizes the ToolDiscovery module in packages/mcp/src/tool-discovery.ts. This implementation sends paginated HTTP GET requests to the /tools?page=… endpoint, streaming JSON Schema definitions and metadata back to the client.

The discovery routine enforces strict resource limits:

• Maximum tool count per server
• Individual definition size limits
• Maximum pagination depth

If limits are exceeded or duplicate tool definitions are detected, the discovery process aborts for that specific server to prevent resource exhaustion.

Schema Validation and Descriptor Creation

Each received definition undergoes processing by ToolOutputValidation in packages/mcp/src/tool-output-validation.ts. Valid tools are wrapped in McpToolDescriptor objects containing the server ID, tool name, description, and admission policies. This abstraction layer decouples the transport-specific implementation from the runtime execution environment.

Step 3: Runtime Integration and Execution

After validation, tools must be registered with the runtime environment and made available for invocation.

Capability Coordination with RuntimeHost

The RuntimeHost in packages/runtime-host/src receives validated McpToolDescriptor instances through the client-capability coordinator located in packages/runtime-host/src/protocol/client-capability.ts. For each descriptor, the system creates a Desktop MCP offer prefixed with DESKTOP_MCP_OFFER_PREFIX, registering the tool as an available capability.

Session Scoping and Security

Each offer is bound to the current Session Grant, ensuring that only the session that requested the MCP server can invoke its tools. This security model prevents cross-session tool access and maintains isolation between different client contexts.

Lazy Loading and Sandbox Execution

MCP tools employ lazy loading—they are not instantiated until the first invocation. When triggered, the Runtime uses the stored descriptor to open a network-bound call to the originating server via the implementation in packages/runtime/src/mcp-tools.ts. The system applies required sandbox permissions and streams execution results back to the client.

Dynamic Configuration Updates

Maka supports hot-reloading of MCP configurations. Changes to mcp-config.json trigger automatic detection; the McpManager re-runs the discovery pipeline, and new tool offers appear in the UI without requiring an application restart. This dynamic behavior enables zero-downtime updates to the tool provider ecosystem.

Practical Implementation Examples

The following examples demonstrate programmatic interaction with the discovery system.

Adding an MCP server programmatically:

import { McpConfigStore } from '@maka/storage';
import { resolveMcpProtocolPreference } from '@maka/core/mcp';

async function addMcpServer(id: string, rawUrl: string) {
  const store = new McpConfigStore();
  const protocol = resolveMcpProtocolPreference(rawUrl);
  await store.updateConfig(cfg => {
    cfg.mcpServers[id] = { url: protocol };
  });
  // The manager automatically detects the new entry on the next discovery run
}

Listing discovered MCP tools at runtime:

import { Runtime } from '@maka/runtime';

async function listMcpTools(runtime: Runtime) {
  const mcpTools = runtime.capabilityCoordinator
    .getAllOffers()
    .filter(o => o.offerId.startsWith('desktop_mcp'));
  
  return mcpTools.map(t => ({
    serverId: t.descriptor.serverId,
    name: t.descriptor.name,
    description: t.descriptor.description,
  }));
}

Summary

• Configuration Persistence: Maka stores MCP server definitions in mcp-config.json, managed by McpConfigStore in packages/storage/src/mcp-config-store.ts.
• Protocol Negotiation: The resolveMcpProtocolPreference function in packages/mcp/src/index.ts selects the most secure available transport protocol.
• Discovery Pipeline: ToolDiscovery in packages/mcp/src/tool-discovery.ts paginates tool listings and enforces limits on tool counts and definition sizes.
• Validation Layer: ToolOutputValidation ensures schema compliance before tools are wrapped in McpToolDescriptor instances.
• Runtime Registration: The capability coordinator in packages/runtime-host/src/protocol/client-capability.ts registers tools as session-scoped offers with the DESKTOP_MCP_OFFER_PREFIX.
• Dynamic Updates: Configuration changes trigger automatic rediscovery without requiring application restarts.

Frequently Asked Questions

How does Maka handle duplicate tool definitions from multiple MCP servers?

The ToolDiscovery module in packages/mcp/src/tool-discovery.ts detects duplicate tool identifiers during the paginated fetch process. When duplicates are encountered, the discovery routine aborts for that specific server, preventing namespace collisions and ensuring tool uniqueness across the runtime environment.

What transport protocols does Maka support for MCP server connections?

Maka supports http, https, ws (WebSocket), and wss (WebSocket Secure) protocols. The resolveMcpProtocolPreference helper selects the most secure option available, prioritizing encrypted connections. The McpManager then establishes either STDIO or WebSocket channels depending on the server capabilities and configuration.

Can MCP servers be added without restarting the Maka application?

Yes. Maka implements hot-reloading for MCP configurations. Changes to mcp-config.json are automatically detected by the McpConfigStore, triggering the McpManager to re-run discovery. New tools appear in the user interface immediately through the dynamic registration mechanism in packages/runtime-host/src/protocol/client-capability.ts.

How does Maka secure MCP tool execution?

Security is enforced through Session Grant scoping. When RuntimeHost registers tools via the capability coordinator, each McpToolDescriptor is bound to the specific session that requested it. Additionally, ToolOutputValidation in packages/mcp/src/tool-output-validation.ts validates all tool schemas before registration, and the runtime applies sandbox permissions during tool invocation in packages/runtime/src/mcp-tools.ts.

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