How to Configure MCP Integrations in AIOX: Complete Setup Guide

Configure MCP integrations in AIOX by enabling the MCP selection wizard in packages/installer/src/wizard/questions.js, running the installProjectMCPs installer to generate a .mcp.json file, and validating the setup with the validateMCPs health-checker.

The AIOX framework from SynkraAI extends its core AI engine through Model Context Protocol (MCP) servers, adding specialized capabilities like browser automation, documentation search, and web search. Configuring these integrations follows a three-step flow involving wizard selection, JSON configuration generation, and health validation as implemented in the aiox-core repository.

Enabling MCP Selection in the Installation Wizard

By default, the AIOX installer hides the MCP selection question to streamline the setup process. To expose the MCP configuration options during project initialization, you must modify the question sequence builder in the installer source code.

In packages/installer/src/wizard/questions.js, the getMCPQuestions() function constructs a checkbox prompt listing the four bundled MCPs: Browser, Context7, Exa, and Desktop Commander. To enable this prompt, uncomment the insertion line inside buildQuestionSequence:

// packages/installer/src/wizard/questions.js
function buildQuestionSequence(_context = {}) {
  const questions = [];

  // … (language, projectType, IDE)
  questions.push(...getIDEQuestions());

  // <--- Enable MCP selection
  // Uncomment the line below to let users pick MCPs during init
  // questions.push(...getMCPQuestions());

  // … (tech preset, etc.)
  return questions;
}

Uncommenting questions.push(...getMCPQuestions()) exposes the interactive selection interface during the next aiox init execution.

Installing MCP Servers with the Installer Module

Once you have selected your desired MCPs—either through the wizard or programmatically—the installProjectMCPs() function in bin/modules/mcp-installer.js handles the actual installation. This module validates NPM packages, generates per-MCP launch configurations via getConfig, and persists the settings to .mcp.json.

For automated setups or CI/CD pipelines, invoke the installer programmatically:

// Example: programmatic installation (e.g., from a custom script)
const { installProjectMCPs, displayInstallationStatus } = require('../bin/modules/mcp-installer');

async function setupMCPs() {
  const result = await installProjectMCPs({
    selectedMCPs: ['browser', 'context7', 'exa'], // Choose any subset
    projectPath: process.cwd(),
    apiKeys: { EXA_API_KEY: process.env.EXA_API_KEY }, // optional
    onProgress: console.log,
  });

  displayInstallationStatus(result);
}

setupMCPs().catch(console.error);

The installer writes a .mcp.json file at the project root with the following schema:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server", "--tools=web_search_exa,research_paper_search,company_research,crawling,competitor_finder,linkedin_search,wikipedia_search_exa,github_search"],
      "env": {
        "EXA_API_KEY": "${EXA_API_KEY}"
      }
    }
  }
}

All bundled MCPs use the stdio transport via npx (or cmd /c on Windows), ensuring cross-platform compatibility without additional network configuration.

Configuring API Keys and Environment Variables

Sensitive credentials are never baked directly into .mcp.json. Instead, the installer inserts placeholder variables like ${EXA_API_KEY} for services requiring authentication. You must provide the actual values in your project's .env file:

EXA_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

AIOX loads environment variables from .env at runtime, substituting the placeholders when spawning MCP server processes. This separation keeps secrets out of version control while maintaining portable configuration files.

Validating MCP Configuration with Health Checks

Before relying on MCP integrations in production, run the health-check validator to catch configuration errors early. The validateMCPs() function in packages/installer/src/wizard/validation/validators/mcp-health-checker.js reads .mcp.json and performs lightweight sanity checks—verifying command existence, API key placeholders, and argument validity—without fully launching the servers.

Execute the validator programmatically:

const { validateMCPs } = require('../packages/installer/src/wizard/validation/validators/mcp-health-checker');

async function healthCheck() {
  const ctx = {
    installedMCPs: { browser: { status: 'success' },
                    context7: { status: 'success' },
                    exa: { status: 'success' } },
    configPath: '.mcp.json',
  };

  const report = await validateMCPs(ctx);
  console.log(JSON.stringify(report, null, 2));
}

healthCheck();

The function returns a structured report indicating success, warnings (such as unset API key placeholders), or critical configuration errors:

{
  "success": true,
  "healthChecks": [
    { "mcp": "browser", "status": "success", "message": "Configuration valid (runtime test requires browser launch)" },
    { "mcp": "context7", "status": "success", "message": "Configuration valid (runtime test requires MCP server launch)" },
    { "mcp": "exa", "status": "warning", "message": "API key is placeholder - update .env with real key" }
  ],
  "warnings": [
    {
      "severity": "low",
      "message": "exa health check warning: API key is placeholder - update .env with real key",
      "code": "MCP_HEALTH_CHECK_WARNING",
      "mcp": "exa"
    }
  ],
  "errors": []
}

Runtime Behavior and Lazy Loading

When an AIOX command requires MCP functionality, the framework reads the corresponding entry from .mcp.json and spawns the configured command via npx or cmd. According to the aiox-core implementation, servers start lazily on first use, meaning only the JSON configuration is required at install time; the actual browser or network connections initialize when the AI agent first invokes the tool.

Summary

• Enable MCP selection by uncommenting questions.push(...getMCPQuestions()) in packages/installer/src/wizard/questions.js to expose the wizard interface.
• Generate configuration by running installProjectMCPs() from bin/modules/mcp-installer.js, which creates .mcp.json with stdio transport commands.
• Secure credentials using ${VARIABLE} placeholders in .mcp.json and real values in the project .env file.
• Validate setup by executing validateMCPs() from packages/installer/src/wizard/validation/validators/mcp-health-checker.js to verify commands and API keys before runtime.

Frequently Asked Questions

Where does AIOX store MCP configuration files?

AIOX persists MCP server configurations in a .mcp.json file located at the project root. The installer generates this file automatically when you run installProjectMCPs(), populating it with command paths, arguments, and environment variable placeholders for each selected MCP server.

How do I securely add API keys for MCP integrations like Exa?

The installer inserts placeholder strings such as ${EXA_API_KEY} into the .mcp.json environment configuration. You provide the actual secret in your project's .env file (e.g., EXA_API_KEY=sk-...), which AIOX loads at runtime to substitute the placeholder when spawning the MCP process.

Can I install MCP servers without using the interactive wizard?

Yes. Import and call installProjectMCPs() directly from bin/modules/mcp-installer.js in any Node.js script or automation pipeline. Pass an array of MCP IDs to selectedMCPs, specify the projectPath, and optionally provide apiKeys and an onProgress callback to handle the installation programmatically without user interaction.

How do I verify that my MCP configuration is valid before running AIOX?

Run the validateMCPs() function from packages/installer/src/wizard/validation/validators/mcp-health-checker.js. This utility checks that commands exist, arguments are properly formatted, and API key placeholders are noted, returning a detailed report with success statuses, warnings, or errors without requiring full server startup.

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