AIOX MCP Global Setup Guide

EN | PT | ES

Configure global MCP (Model Context Protocol) servers for Synkra AIOX.

Version: 2.1.1 Last Updated: 2025-12-23

Overview

The MCP Global System allows you to configure MCP servers once and share them across all AIOX projects. This eliminates the need to configure the same servers in every project.

Benefits

| Benefit | Description | | ------------------------- | --------------------------------------- | | Single Configuration | Configure servers once, use everywhere | | Consistent Settings | Same server configs across all projects | | Credential Management | Secure, centralized credential storage | | Easy Updates | Update server versions in one place |

Global Directory Structure

~/.aiox/
├── mcp/
│   ├── global-config.json    # Main configuration file
│   ├── servers/              # Individual server configs
│   │   ├── context7.json
│   │   ├── exa.json
│   │   └── github.json
│   └── cache/                # Server response cache
└── credentials/              # Secure credential storage
    └── .gitignore            # Prevents accidental commits

Recommended Architecture

Based on production configurations, the recommended MCP setup uses two layers:

┌─────────────────────────────────────────────────────────────┐
│                    ~/.claude.json                            │
│                   (User MCPs - Direct)                       │
├─────────────────────────────────────────────────────────────┤
│  desktop-commander  │ Persistent sessions, REPL, fuzzy edit │
│  docker-gateway     │ Gateway for containerized MCPs        │
│  playwright         │ Browser automation                    │
│  n8n-mcp           │ Workflow automation (optional)         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              docker-gateway (58+ tools)                      │
│            (MCPs inside Docker - No token cost)              │
├─────────────────────────────────────────────────────────────┤
│  Apify        │ Web scraping, social media extraction       │
│  Context7     │ Library documentation lookup                │
│  EXA          │ Web search and research                     │
│  + others     │ Any MCP that runs in containers             │
└─────────────────────────────────────────────────────────────┘

Why this architecture?

| MCP Location | Token Cost | Use Case | | ---------------------------- | ----------------- | -------------------------------------------- | | Direct in ~/.claude.json | Normal | MCPs that need host access (files, terminal) | | Inside docker-gateway | No extra cost | MCPs that don't need host access (APIs, web) |

MCPs running inside docker-gateway are encapsulated in containers, so their tool definitions don't add overhead to the Claude conversation context.

Platform-Specific Paths

Windows

C:\Users\<username>\.aiox\mcp\global-config.json
C:\Users\<username>\.aiox\mcp\servers\
C:\Users\<username>\.aiox\credentials\

macOS

/Users/<username>/.aiox/mcp/global-config.json
/Users/<username>/.aiox/mcp/servers/
/Users/<username>/.aiox/credentials/

Linux

/home/<username>/.aiox/mcp/global-config.json
/home/<username>/.aiox/mcp/servers/
/home/<username>/.aiox/credentials/

Initial Setup

Step 1: Create Global Structure

# Create global directory and config
aiox mcp setup

This creates:

~/.aiox/ - Global AIOX directory
~/.aiox/mcp/ - MCP configuration directory
~/.aiox/mcp/global-config.json - Main config file
~/.aiox/mcp/servers/ - Individual server configs
~/.aiox/mcp/cache/ - Response cache
~/.aiox/credentials/ - Secure credential storage

Step 2: Verify Setup

# Check global config exists
aiox mcp status

Expected Output:

MCP Global Configuration
========================

Location: ~/.aiox/mcp/global-config.json
Status:   ✓ Configured

Servers: 0 configured
Cache:   Empty

Run 'aiox mcp add <server>' to add servers.

Adding MCP Servers

Using Templates

AIOX includes templates for popular MCP servers:

# Add from template
aiox mcp add context7
aiox mcp add exa
aiox mcp add github
aiox mcp add puppeteer
aiox mcp add filesystem
aiox mcp add memory
aiox mcp add desktop-commander

Available Templates

| Template | Type | Description | | ------------------- | ------- | ----------------------------- | | context7 | SSE | Library documentation lookups | | exa | Command | Advanced web search | | github | Command | GitHub API integration | | puppeteer | Command | Browser automation | | filesystem | Command | File system access | | memory | Command | Temporary memory storage | | desktop-commander | Command | Desktop automation |

Custom Server Configuration

# Add custom server with JSON config
aiox mcp add my-server --config='{"command":"npx","args":["-y","my-mcp-server"]}'

# Add from config file
aiox mcp add my-server --config-file=./my-server-config.json

CLI Commands

`aiox mcp setup`

Initialize global MCP configuration.

# Create global structure
aiox mcp setup

# Force recreate (backup existing)
aiox mcp setup --force

# Specify custom location
aiox mcp setup --path=/custom/path

`aiox mcp add`

Add a new MCP server.

# Add from template
aiox mcp add context7

# Add with custom config
aiox mcp add custom-server --config='{"command":"npx","args":["-y","package"]}'

# Add with environment variables
aiox mcp add exa --env='EXA_API_KEY=your-key'

`aiox mcp remove`

Remove an MCP server.

# Remove server
aiox mcp remove context7

# Remove with confirmation skip
aiox mcp remove context7 --yes

`aiox mcp list`

List configured servers.

# List all servers
aiox mcp list

# List with details
aiox mcp list --verbose

# List only enabled
aiox mcp list --enabled

Output:

Configured MCP Servers
======================

  context7     [enabled]  SSE  https://mcp.context7.com/sse
  exa          [enabled]  CMD  npx -y exa-mcp-server
  github       [disabled] CMD  npx -y @modelcontextprotocol/server-github

Total: 3 servers (2 enabled, 1 disabled)

`aiox mcp enable/disable`

Enable or disable servers.

# Disable server
aiox mcp disable github

# Enable server
aiox mcp enable github

# Toggle
aiox mcp toggle github

`aiox mcp status`

Show global MCP status.

# Full status
aiox mcp status

# JSON output
aiox mcp status --json

`aiox mcp sync`

Sync global config to project.

# Sync to current project
aiox mcp sync

# Sync specific servers only
aiox mcp sync --servers=context7,exa

Configuration Files

global-config.json

Main configuration file with all server definitions.

{
  "version": "1.0",
  "servers": {
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.com/sse",
      "enabled": true
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "${EXA_API_KEY}"
      },
      "enabled": true
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "enabled": true
    }
  },
  "defaults": {
    "timeout": 30000,
    "retries": 3
  }
}

Individual Server Files

Each server also has its own config file in servers/:

// ~/.aiox/mcp/servers/context7.json
{
  "type": "sse",
  "url": "https://mcp.context7.com/sse",
  "enabled": true
}

Server Types

SSE (Server-Sent Events)

For servers that provide a streaming HTTP endpoint.

{
  "type": "sse",
  "url": "https://mcp.server.com/sse",
  "enabled": true
}

Command

For servers that run as local processes.

{
  "command": "npx",
  "args": ["-y", "@package/mcp-server"],
  "env": {
    "API_KEY": "${API_KEY}"
  },
  "enabled": true
}

Windows Command Wrapper

For Windows, use the CMD wrapper for NPX:

{
  "command": "cmd",
  "args": ["/c", "npx-wrapper.cmd", "-y", "@package/mcp-server"],
  "env": {
    "API_KEY": "${API_KEY}"
  },
  "enabled": true
}

Environment Variables

Using Variables in Config

Reference environment variables using ${VAR_NAME} syntax:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "TOKEN": "${MY_TOKEN}"
  }
}

Setting Variables

Windows (PowerShell):

$env:EXA_API_KEY = "your-api-key"
$env:GITHUB_TOKEN = "your-github-token"

Windows (CMD):

set EXA_API_KEY=your-api-key
set GITHUB_TOKEN=your-github-token

macOS/Linux:

export EXA_API_KEY="your-api-key"
export GITHUB_TOKEN="your-github-token"

Persistent Variables

Windows: Add to System Environment Variables

macOS/Linux: Add to ~/.bashrc, ~/.zshrc, or ~/.profile:

export EXA_API_KEY="your-api-key"
export GITHUB_TOKEN="your-github-token"

Credential Management

Secure Storage

Credentials are stored in ~/.aiox/credentials/ with a .gitignore to prevent accidental commits.

# Add credential
aiox mcp credential set EXA_API_KEY "your-api-key"

# Get credential
aiox mcp credential get EXA_API_KEY

# List credentials (masked)
aiox mcp credential list

Credential File Format

// ~/.aiox/credentials/api-keys.json
{
  "EXA_API_KEY": "encrypted-value",
  "GITHUB_TOKEN": "encrypted-value"
}

Programmatic Usage

JavaScript API

const {
  globalDirExists,
  globalConfigExists,
  createGlobalStructure,
  readGlobalConfig,
  addServer,
  removeServer,
  listServers,
} = require('./.aiox-core/core/mcp/global-config-manager');

// Check if setup exists
if (!globalDirExists()) {
  createGlobalStructure();
}

// Add server
addServer('my-server', {
  command: 'npx',
  args: ['-y', 'my-mcp-server'],
  enabled: true,
});

// List servers
const { servers, total, enabled } = listServers();
console.log(`${enabled}/${total} servers enabled`);

// Remove server
removeServer('my-server');

OS Detection

const {
  detectOS,
  isWindows,
  isMacOS,
  isLinux,
  getGlobalMcpDir,
  getGlobalConfigPath,
} = require('./.aiox-core/core/mcp/os-detector');

// Get OS type
console.log(detectOS()); // 'windows' | 'macos' | 'linux'

// Get paths
console.log(getGlobalMcpDir()); // ~/.aiox/mcp/
console.log(getGlobalConfigPath()); // ~/.aiox/mcp/global-config.json

Troubleshooting

Setup Issues

| Issue | Solution | | ----------------- | ----------------------------------------------------------------- | | Permission denied | Run terminal as Administrator (Windows) or use sudo (macOS/Linux) | | Directory exists | Use aiox mcp setup --force to recreate | | Path not found | Ensure home directory exists |

Server Issues

| Issue | Solution | | ------------------------------ | ------------------------------------------------ | | Server not starting | Check command and args, verify package installed | | Environment variable not found | Set variable or use credentials storage | | Timeout errors | Increase timeout in config | | Connection refused | Check URL and network access |

Windows-Specific Issues

| Issue | Solution | | -------------- | -------------------------------------- | | NPX not found | Add Node.js to PATH, use CMD wrapper | | Symlink errors | Enable Developer Mode or use junctions | | Path too long | Enable long paths in registry |

Common Fixes

# Reset global config
aiox mcp setup --force

# Clear cache
rm -rf ~/.aiox/mcp/cache/*

# Verify config
aiox mcp status --verbose

# Test server manually
npx -y @modelcontextprotocol/server-github

Docker MCP Toolkit Issues

| Issue | Solution | | -------------------------------- | ----------------------------------------- | | Secrets not passed to containers | Edit catalog file directly (see below) | | Template interpolation failing | Use hardcoded values in catalog | | Tools showing as "(N prompts)" | Token not being passed - apply workaround |

Docker MCP Secrets Bug (Dec 2025)

Issue: Docker MCP Toolkit's secrets store (docker mcp secret set) and template interpolation ({{...}}) do NOT work properly. Credentials are not passed to containers.

Symptoms:

docker mcp tools ls shows "(N prompts)" instead of "(N tools)"
MCP server starts but fails authentication
Verbose output shows -e ENV_VAR without values

Workaround: Edit ~/.docker/mcp/catalogs/docker-mcp.yaml directly:

{ mcp-name }:
  env:
    - name: API_TOKEN
      value: 'actual-token-value-here'

Example - Apify:

apify-mcp-server:
  env:
    - name: TOOLS
      value: 'actors,docs,apify/rag-web-browser'
    - name: APIFY_TOKEN
      value: 'apify_api_xxxxxxxxxxxxx'

Note: This exposes credentials in a local file. Secure file permissions and never commit this file.

Integration with IDE

Claude Desktop

Add to Claude Desktop settings:

{
  "mcpServers": {
    "aiox-global": {
      "command": "aiox",
      "args": ["mcp", "serve", "--global"]
    }
  }
}

VS Code

Configure in .vscode/settings.json:

{
  "aiox.mcp.useGlobal": true,
  "aiox.mcp.globalPath": "~/.aiox/mcp/global-config.json"
}

Project-Specific Override

Create .mcp.json in project root to override global settings:

{
  "inherit": "global",
  "servers": {
    "context7": {
      "enabled": false
    },
    "project-specific": {
      "command": "node",
      "args": ["./local-mcp-server.js"]
    }
  }
}

Best Practices

Use templates for common servers
Store credentials securely in credentials directory
Disable unused servers to reduce resource usage
Keep servers updated with latest package versions
Use project overrides for project-specific needs
Back up config before major changes