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

> Learn how Apache Maka discovers and loads MCP servers. This guide details the McpConfigStore, protocol resolution, ToolDiscovery pipeline, and RuntimeHost registration for efficient server management.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-09

---

**Maka discovers MCP servers by reading** [`mcp-config.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/apache/maka/blob/main/mcp-config.json), managed by `McpConfigStore` in [`packages/storage/src/mcp-config-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/mcp-config-store.ts).
- **Protocol Negotiation**: The `resolveMcpProtocolPreference` function in [`packages/mcp/src/index.ts`](https://github.com/apache/maka/blob/main/packages/mcp/src/index.ts) selects the most secure available transport protocol.
- **Discovery Pipeline**: `ToolDiscovery` in [`packages/mcp/src/tool-discovery.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/mcp-tools.ts).