Troubleshooting Guide

Common issues and solutions for FAOS MCP integration with Claude Desktop.

Quick Diagnostics

Run these checks first:

# 1. Verify MCP server installed
faos-mcp --version

# 2. Validate config JSON
cat ~/.config/claude/mcp.json | python -m json.tool

# 3. Test API connectivity
curl -H "Authorization: Bearer $FAOS_API_TOKEN" https://api.faosx.ai/health

Installation Issues

"faos-mcp: command not found"

Symptom: faos-mcp --version returns "command not found"

Causes:

Package not installed
Not in PATH
Virtual environment not activated

Solutions:

Verify installation:

# Check if installed
pip show faos-mcp
# Or for pipx
pipx list | grep faos-mcp

Reinstall:

pipx install faos-mcp
# Ensure PATH is updated
pipx ensurepath
# Restart terminal

Use full path in config:

{
  "servers": {
    "faos": {
      "command": "/Users/yourname/.local/bin/faos-mcp"
    }
  }
}

Find the path:

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

"Python version not supported"

Symptom: Installation fails with Python version error

Solutions:

Check version:

python --version
# Must be 3.10+

Use pyenv to install correct version:

pyenv install 3.11.0
pyenv global 3.11.0

Use pipx with specific Python:

pipx install faos-mcp --python python3.11

Configuration Issues

"MCP server not found" / Tools not appearing

Symptom: Claude doesn't show FAOS tools when asked

Solutions:

Check config file location:

OS	Path
macOS	`~/.config/claude/mcp.json`
Windows	`%APPDATA%\claude\mcp.json`
Linux	`~/.config/claude/mcp.json`

Validate JSON syntax:

cat ~/.config/claude/mcp.json | python -m json.tool

Common JSON errors:

Missing commas between properties
Trailing commas (not allowed in JSON)
Unquoted strings
Wrong quote characters (use ", not ' or ")

Check server name spelling:

{
  "servers": {
    "faos": {
      "command": "faos-mcp"
    }
  }
}

Completely restart Claude Desktop:

macOS: Quit from menu bar (not just close window)
Windows: Exit from system tray
Linux: pkill -f claude && sleep 2 && claude-desktop

Check Claude logs:

macOS: ~/Library/Logs/Claude/
Windows: %APPDATA%\Claude\logs\

"Invalid JSON in config"

Symptom: Config file rejected

Common fixes:

Trailing comma (wrong)

{
  "servers": {
    "faos": {
      "command": "faos-mcp",
    }
  }
}

Remove the trailing comma after "faos-mcp"

Single quotes (wrong)

{
  'servers': {
    ...
  }
}

Use double quotes " not single quotes '

Comments (wrong)

{
  "servers": {
    // This is a comment
    "faos": { ... }
  }
}

JSON does not support comments - remove them

Correct format

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

Authentication Issues

"Authentication failed" (401)

Symptom: Error 401 when invoking tools

Solutions:

Verify token is valid:

Log in to FAOS Portal
Go to Settings → API Tokens
Check token hasn't expired or been revoked

Regenerate token:

In portal: Settings → API Tokens → Generate New Token
Update mcp.json with new token
Restart Claude Desktop

Check for typos:

Ensure no extra spaces in token
Verify token is properly quoted

Check API URL:

// Production
"FAOS_API_URL": "https://api.faosx.ai"

// Staging (if applicable)
"FAOS_API_URL": "https://staging-api.faosx.ai"

"Insufficient permissions" (403)

Symptom: Error 403 when using specific tools

Solutions:

Check token scopes:

In portal: Settings → API Tokens → View token details
Ensure required scopes are enabled

Required scopes by tool:

Tool	Required Scope
`faos_invoke_agent`	`agents:invoke`
`faos_run_workflow`	`workflows:run`
`faos_get_context`	`context:read`
`faos_query_metric`	`metrics:read`
`faos_query_graph`	`graph:read`

Generate new token with correct scopes:

Delete old token
Create new token with all needed scopes
Update config and restart

Symptom: Browser keeps asking for login

Solutions:

Clear browser cookies:

Clear cookies for your IdP domain
Clear cookies for *.faosx.ai

Try incognito/private window:

Sometimes extensions interfere

Clear FAOS auth cache:

rm ~/.faos/auth_cache.json
faos-mcp auth clear

Check IdP configuration:

Verify redirect URIs in IdP admin
Contact your IT admin for SSO issues

Runtime Issues

"Tool not found"

Symptom: Claude says it can't find a specific FAOS tool

Solutions:

Check tool name spelling:

Tool names are case-sensitive
Use exact names: faos_invoke_agent, not faos-invoke-agent

Verify tools are loaded:

"List all available FAOS tools"

Restart Claude Desktop:

New tools may not appear until restart

Check MCP server logs:

# Run manually to see errors
FAOS_API_TOKEN=your_token FAOS_API_URL=https://api.faosx.ai faos-mcp

"Rate limit exceeded" (429)

Symptom: Error 429, requests rejected

Solutions:

Wait and retry:

Default: Wait 60 seconds
Rate limits reset per minute

Reduce request frequency:

Batch related queries
Avoid rapid-fire tool calls

Check your plan limits:

Free tier: 100 requests/hour
Pro tier: 1000 requests/hour
Enterprise: Custom limits

Upgrade plan:

Contact support@faosx.ai for higher limits

"Timeout during workflow" (504)

Symptom: Long-running workflows fail

Solutions:

Use async execution:

Don't: "Run FAOS create-prd workflow and wait for completion"
Do:    "Run FAOS create-prd workflow" (returns immediately)
       "Check status of workflow wfrun_abc123" (poll later)

Check workflow status separately:

"What's the status of FAOS workflow wfrun_abc123?"

For long workflows, expect async:

create-prd: 30-60 minutes
create-architecture: 45-90 minutes
Always use wait_for_completion: false

"Connection refused"

Symptom: Can't connect to FAOS API

Solutions:

Check internet connectivity:

ping api.faosx.ai
curl https://api.faosx.ai/health

Check firewall/VPN:

Corporate VPNs may block external APIs
Whitelist *.faosx.ai

Check API URL:

Ensure no typos
Use HTTPS, not HTTP

Check service status:

FAOS Status Page

Agent-Specific Issues

"Agent not responding" / Slow responses

Solutions:

Try a different agent:

"Use FAOS pm agent instead of auto-routing"

Simplify the task:

Break complex tasks into smaller pieces
Provide clearer instructions

Check agent availability:

"List available FAOS agents"

"Auto-routing selected wrong agent"

Solutions:

Be explicit about the domain:

"I need HELP WITH ARCHITECTURE for..." (emphasize domain)

Specify agent directly:

"Use the FAOS architect agent to..."

Provide more context:

Include relevant keywords
Mention the type of output you need

Workflow-Specific Issues

"Workflow stuck at step X"

Solutions:

Check status:

"Get detailed status of FAOS workflow wfrun_abc123"

Wait longer:

Some steps take time (research, analysis)
Check progress percentage

Cancel and retry:

"Cancel FAOS workflow wfrun_abc123" "Run FAOS [workflow] with [modified inputs]"

Report issue:

If stuck for >30 minutes past estimated time
Contact support with workflow_run_id

"Workflow output incomplete"

Solutions:

Check if actually complete:

Status should be completed, not running

Verify inputs were correct:

Missing required inputs cause incomplete outputs

Re-run with better inputs:

Add more context
Be more specific about requirements

Getting Help

Self-Service

Check this guide for common issues
Search documentation at docs.faosx.ai
Community Discord at discord.gg/faosx

Support Channels

Issue Type	Channel	Response Time
Bug reports	GitHub Issues	24-48 hours
Account issues	support@faosx.ai	24 hours
Enterprise support	Dedicated Slack channel	4 hours
Security issues	security@faosx.ai	Immediate

Information to Include

When reporting issues:

Environment:
- OS and version
- Claude Desktop version
- faos-mcp version (faos-mcp --version)
- Python version
Steps to reproduce:
- Exact prompt used
- Expected vs actual behavior
Logs:
- MCP server output (if run manually)
- Claude Desktop logs
- Error messages (full text)
Config:
- Your mcp.json (redact token!)

Quick Diagnostics​

Installation Issues​

"faos-mcp: command not found"​

"Python version not supported"​

Configuration Issues​

"MCP server not found" / Tools not appearing​

"Invalid JSON in config"​

Authentication Issues​

"Authentication failed" (401)​

"Insufficient permissions" (403)​

"SSO login loop"​

Runtime Issues​

"Tool not found"​

"Rate limit exceeded" (429)​

"Timeout during workflow" (504)​

"Connection refused"​

Agent-Specific Issues​

"Agent not responding" / Slow responses​

"Auto-routing selected wrong agent"​

Workflow-Specific Issues​

"Workflow stuck at step X"​

"Workflow output incomplete"​

Getting Help​

Self-Service​

Support Channels​

Information to Include​

Quick Diagnostics

Installation Issues

"faos-mcp: command not found"

"Python version not supported"

Configuration Issues

"MCP server not found" / Tools not appearing

"Invalid JSON in config"

Authentication Issues

"Authentication failed" (401)

"Insufficient permissions" (403)

"SSO login loop"

Runtime Issues

"Tool not found"

"Rate limit exceeded" (429)

"Timeout during workflow" (504)

"Connection refused"

Agent-Specific Issues

"Agent not responding" / Slow responses

"Auto-routing selected wrong agent"

Workflow-Specific Issues

"Workflow stuck at step X"

"Workflow output incomplete"

Getting Help

Self-Service

Support Channels

Information to Include