Installation Guide

Detailed installation instructions for FAOS MCP Server with Claude Desktop.

Prerequisites

Required

Requirement	Version	Check Command
Claude Desktop	Latest	Check "About Claude" in app
Python	3.10+	python --version
pip or pipx	Latest	pip --version or pipx --version

Recommended

Tool	Purpose
pipx	Isolated Python app installation
jq	JSON validation and formatting

Installation Methods

Method 1: pipx (Recommended)

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 System	Path
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

Via Portal (Recommended)

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

Scope	Purpose	Required For
agents:invoke	Invoke specialist agents	faos_invoke_agent
workflows:run	Execute workflows	faos_run_workflow
context:read	Read project context	faos_get_context, faos_get_story
activities:write	Log developer activities	faos_log_activity
metrics:read	Query business metrics	faos_query_metric
graph:read	Query knowledge graph	faos_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

• Authentication Setup - SSO, enterprise auth, token management
• Tool Reference - All 17 tools with detailed examples
• Troubleshooting - Common issues and solutions