Skip to main content

Installation Guide

Detailed installation instructions for FAOS MCP Server with Claude Desktop.

Prerequisites​

Required​

RequirementVersionCheck Command
Claude DesktopLatestCheck "About Claude" in app
Python3.10+python --version
pip or pipxLatestpip --version or pipx --version
ToolPurpose
pipxIsolated Python app installation
jqJSON validation and formatting

Installation Methods​

pipx installs Python applications in isolated environments, preventing dependency conflicts.

# Install pipx if needed
python -m pip install --user pipx
python -m pipx ensurepath

# Install FAOS MCP
pipx install faos-mcp

# Verify
faos-mcp --version

Method 2: pip (Global)​

# Install globally
pip install faos-mcp

# Or in a virtual environment
python -m venv faos-env
source faos-env/bin/activate  # On Windows: faos-env\Scripts\activate
pip install faos-mcp

Method 3: From Source​

# Clone the repository
git clone https://github.com/faosx/faos-mcp.git
cd faos-mcp

# Install with uv (recommended for development)
uv sync
uv run faos-mcp --version

MCP Configuration​

Config File Locations​

Operating SystemPath
macOS~/.config/claude/mcp.json
Windows%APPDATA%\claude\mcp.json
Linux~/.config/claude/mcp.json

Creating the Config File​

macOS/Linux:

# Create directory if it doesn't exist
mkdir -p ~/.config/claude

# Create or edit config
nano ~/.config/claude/mcp.json

Windows (PowerShell):

# Create directory if it doesn't exist
New-Item -ItemType Directory -Force -Path "$env:APPDATA\claude"

# Open in notepad
notepad "$env:APPDATA\claude\mcp.json"

Basic Configuration​

{
  "servers": {
    "faos": {
      "command": "faos-mcp",
      "env": {
        "FAOS_API_URL": "https://api.faosx.ai",
        "FAOS_API_TOKEN": "your-token-here"
      }
    }
  }
}

Configuration with Custom Python Path​

If faos-mcp isn't in your PATH:

{
  "servers": {
    "faos": {
      "command": "/full/path/to/faos-mcp",
      "env": {
        "FAOS_API_URL": "https://api.faosx.ai",
        "FAOS_API_TOKEN": "your-token-here"
      }
    }
  }
}

Find the path with:

# pipx installation
which faos-mcp  # macOS/Linux
where faos-mcp  # Windows

# pip installation
python -c "import faos_mcp; print(faos_mcp.__file__)"

Configuration with uvx (No Pre-installation)​

If you prefer not to install faos-mcp globally:

{
  "servers": {
    "faos": {
      "command": "uvx",
      "args": ["faos-mcp"],
      "env": {
        "FAOS_API_URL": "https://api.faosx.ai",
        "FAOS_API_TOKEN": "your-token-here"
      }
    }
  }
}

Validate JSON Syntax​

Before restarting Claude Desktop, validate your JSON:

# Using jq
cat ~/.config/claude/mcp.json | jq .

# Using Python
python -m json.tool ~/.config/claude/mcp.json

Getting Your FAOS Token​

  1. Log in to FAOS Portal
  2. Navigate to Settings β†’ API Tokens
  3. Click Generate New Token
  4. Set token name: "Claude Desktop"
  5. Select scopes: agents:invoke, workflows:run, context:read
  6. Copy the token immediately (it won't be shown again)

Token Scopes​

ScopePurposeRequired For
agents:invokeInvoke specialist agentsfaos_invoke_agent
workflows:runExecute workflowsfaos_run_workflow
context:readRead project contextfaos_get_context, faos_get_story
activities:writeLog developer activitiesfaos_log_activity
metrics:readQuery business metricsfaos_query_metric
graph:readQuery knowledge graphfaos_query_graph

Token Security Best Practices​

  • Never commit tokens to version control
  • Rotate tokens regularly (every 90 days recommended)
  • Use minimal scopes needed for your use case
  • Revoke unused tokens in the portal

Restarting Claude Desktop​

Important

Claude Desktop must be completely restarted to load new MCP servers.

macOS​

  1. Click the Claude icon in the menu bar
  2. Select Quit Claude
  3. Reopen Claude Desktop from Applications

Windows​

  1. Right-click Claude in the system tray
  2. Select Exit
  3. Reopen Claude Desktop from Start menu

Linux​

  1. Close all Claude Desktop windows
  2. Kill any remaining processes: pkill -f claude
  3. Reopen Claude Desktop

Verification​

Check Tools Are Available​

Ask Claude:

"List all available FAOS tools"

Expected response includes:

  • faos_invoke_agent
  • faos_run_workflow
  • faos_get_context
  • ... (17 total tools)

Test Basic Functionality​

  1. Test Context:

    "Use faos_get_context to show current sprint status"

  2. Test Agent:

    "Ask the FAOS PM agent to explain what makes a good PRD"

  3. Test Workflow:

    "List available FAOS workflows"

Updating​

pipx​

pipx upgrade faos-mcp

pip​

pip install --upgrade faos-mcp

From Source​

cd faos-mcp
git pull
uv sync

Uninstalling​

pipx​

pipx uninstall faos-mcp

pip​

pip uninstall faos-mcp

Remove Config​

# Remove FAOS from mcp.json (keep other servers)
# Or delete entirely if only using FAOS:
rm ~/.config/claude/mcp.json

Next Steps​