# How to Configure MCP Integrations in AIOX: Complete Setup Guide

> Easily configure MCP integrations in AIOX with our complete setup guide. Learn to enable the wizard, run the installer, and validate your MCPs for seamless project integration.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: how-to-guide
- Published: 2026-03-15

---

**Configure MCP integrations in AIOX by enabling the MCP selection wizard in [`packages/installer/src/wizard/questions.js`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/questions.js), running the `installProjectMCPs` installer to generate a [`.mcp.json`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`:

```javascript
// 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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.mcp.json).

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

```javascript
// 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`](https://github.com/SynkraAI/aiox-core/blob/main/.mcp.json) file at the project root with the following schema:

```json
{
  "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`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

```dotenv
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`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/validation/validators/mcp-health-checker.js) reads [`.mcp.json`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

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

```json
{
  "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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/questions.js) to expose the wizard interface.
- **Generate configuration** by running `installProjectMCPs()` from [`bin/modules/mcp-installer.js`](https://github.com/SynkraAI/aiox-core/blob/main/bin/modules/mcp-installer.js), which creates [`.mcp.json`](https://github.com/SynkraAI/aiox-core/blob/main/.mcp.json) with stdio transport commands.
- **Secure credentials** using `${VARIABLE}` placeholders in [`.mcp.json`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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.