LearnNewsExamplesServices

Agent-Agnostic MCP Server Configuration

This guide explains the agent-agnostic Model Context Protocol (MCP) server configuration system for Neo.mjs, enabling any AI agent to discover and connect to the project's AI tooling infrastructure.

Overview

The Neo.mjs project provides multiple AI services through MCP (Model Context Protocol) servers. These servers give AI agents the tools and context needed to perform complex software engineering tasks. The primary servers include:

  • Knowledge Base Server: Provides semantic search across the entire codebase, documentation, guides, and examples.
  • Memory Core Server: Offers persistent memory for AI agents, storing conversation history and session context.
  • GitHub Workflow Server: Enables interaction with the GitHub repository, including managing issues and pull requests.
  • Chrome DevTools Server: Allows for browser automation and debugging capabilities.

To ensure these services are accessible to any AI agent, the project uses a simple, standardized configuration format that allows an agent's client environment to launch and communicate with these servers. This guide outlines the schema for this configuration and explains how it enables an "agent-agnostic" approach to tooling.

Configuration Principle

Instead of a single, centralized configuration file, the principle is that each agent's client environment has its own configuration for launching MCP servers. This allows for flexibility while maintaining a common pattern.

For example, the Gemini CLI uses the following file:

.gemini/settings.json

This file contains a definition for each MCP server, specifying the command needed to start it.

The Lifecycle Protocol

The agent's client environment (e.g., the Gemini CLI) is responsible for managing the server lifecycle. The protocol is straightforward:

  1. Read Configuration: On startup, the client reads its configuration file (e.g., .gemini/settings.json).
  2. Launch Servers: For each server defined in the mcpServers section, the client executes the specified command with its args as a separate process.
  3. Establish Communication: The client communicates with the launched server process over standard input/output (stdio). The MCP SDK handles the complexities of this communication channel.
  4. Discover Tools: Once the channel is established, the agent can then use tools like ListTools to discover the server's capabilities directly through the established MCP channel.

This approach removes the burden of health checks, port management, and connection protocols from the agent, which can simply focus on using the provided tools.

Configuration Schema

The configuration schema is minimal and focuses only on how to launch the server process. However, it is part of a broader conceptual schema for defining servers.

Server Definition

A server can be defined with the following properties. While the current implementation primarily uses command and args, the other properties are valuable for documentation, discovery, and potential future enhancements.

Property Type Required Description
name string ✓ Human-readable name of the server.
description string A brief explanation of what the server provides.
command string ✓ The command to execute to start the server (e.g., npm, npx).
args array ✓ An array of string arguments to pass to the command.
type enum Defines the transport protocol for communication. While our current servers implicitly use stdio (managed by the SDK and client), other valid types from the MCP specification include streamable-http or sse. This property is key for a client to know how to communicate with the server.
instructions string Human-readable instructions for manual setup or troubleshooting if the server fails to start automatically.
capabilities array Declares the MCP capabilities the server supports, e.g., ["tools", "resources"].
tags array Keywords for categorizing the server, useful for discovery in UIs.

Example (.gemini/settings.json)

The following is a practical, minimal implementation of this schema used by the Gemini CLI. It focuses purely on the properties needed to launch the servers.

{
    "mcpServers": {
        "chrome-devtools": {
            "command": "npx",
            "args"   : ["-y", "chrome-devtools-mcp@latest"]
        },
        "neo.mjs-github-workflow": {
            "command": "npm",
            "args"   : ["run", "ai:mcp-server-github-workflow"]
        },
        "neo.mjs-knowledge-base": {
            "command": "npm",
            "args"   : ["run", "ai:mcp-server-knowledge-base"]
        },
        "neo.mjs-memory-core": {
            "command": "npm",
            "args"   : ["run", "ai:mcp-server-memory-core"]
        }
    }
}

Server-Side Implementation: The SDK-First Approach

The simplicity of the client-side configuration is made possible by the server-side architecture, which is built using the @modelcontextprotocol/sdk.

Key components of a server include:

  1. Dual Transport Architecture: The servers are built to support multiple transport layers depending on the environment:

    • StdioServerTransport: The default behavior. Servers communicate over the standard input/output of their process. This eliminates the need for port management and network configuration, making it perfect for local CLI agents.
    • StreamableHTTPServerTransport (SSE): Configurable via the transport: 'sse' setting. The servers will dynamically load an Express app and expose a unified /mcp endpoint. This is essential for deploying the servers as containerized microservices (e.g., Docker) where stdio is not accessible to remote agents.

  2. openapi.yaml: Each server has an OpenAPI 3 specification that defines the tools it provides. The operationId of each path becomes the tool's name, and the schema and description are used to generate the tool manifest for the agent. This provides a structured, language-agnostic way to define capabilities.

  3. toolService.mjs: A generic service reads the openapi.yaml file and maps the operationId of each tool to its actual JavaScript implementation. This decouples the tool definition from its implementation.

This architecture allows each MCP server to be a self-contained, standalone application whose lifecycle can be managed by any client environment capable of spawning a process and communicating over stdio.

Benefits of the New Approach

  1. Simplified Client Configuration: The agent's client only needs to know how to start a process, not how to connect to a network service.
  2. Robustness: Eliminates network-related issues like port conflicts. Communication is handled by the robust MCP SDK.
  3. True Agnosticism: Any agent client can run the servers as long as it can read a simple JSON config and spawn a child process.
  4. Single Source of Truth: The openapi.yaml file in each server is the definitive source for the tools it provides, ensuring consistency.

See Also