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

Uh oh!

FilesExpand file tree

mcp-global-setup.md

Latest commit

History