Authentication Setup

Configure authentication for FAOS MCP integration with Claude Desktop.

Authentication Methods

FAOS supports multiple authentication methods:

Method	Use Case	Security Level
API Token	Personal use, development	Standard
SSO (SAML/OIDC)	Enterprise deployment	High
Service Account	CI/CD, automation	High

API Token Authentication

Generating a Token

1. Log in to FAOS Portal
2. Navigate to Settings → API Tokens
3. Click Generate New Token
4. Configure:
   • Name: Descriptive name (e.g., "Claude Desktop - MacBook Pro")
   • Expiration: Choose based on security requirements
   • Scopes: Select required permissions

Token Scopes Reference

Scope	Description	Tools Requiring This Scope
agents:invoke	Invoke specialist agents	faos_invoke_agent
workflows:run	Execute multi-step workflows	faos_run_workflow, faos_cancel_workflow
workflows:read	View workflow status	faos_get_workflow_status, faos_list_workflows
context:read	Read project context	faos_get_context, faos_get_story, faos_search_decisions, faos_get_guidelines
activities:write	Log developer activities	faos_log_activity
activities:read	View tasks and activities	faos_get_my_tasks
metrics:read	Query business metrics	faos_query_metric, faos_list_metrics, faos_get_metric_definition
graph:read	Query knowledge graph	faos_query_graph, faos_nl_graph_query, faos_explain_graph_query

Recommended Scope Sets

Developer (Full Access):

agents:invoke, workflows:run, workflows:read, context:read, activities:write, activities:read, metrics:read, graph:read

Analyst (Read-Heavy):

agents:invoke, context:read, metrics:read, graph:read

CI/CD (Automation):

workflows:run, workflows:read, activities:write

Configuring Token in MCP

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

Token from Environment Variable

For added security, reference an environment variable:

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

Then set in your shell profile (~/.zshrc, ~/.bashrc):

export FAOS_API_TOKEN="faosx_abc123..."

SSO Authentication (Enterprise)

For enterprise deployments using SAML or OIDC.

Prerequisites

• FAOS Enterprise license
• Identity Provider (IdP) configured:
  • Okta
  • Azure AD
  • Google Workspace
  • Any SAML 2.0 / OIDC provider

Configuration Steps

1. Admin Portal Setup:

   • Navigate to Admin → SSO Configuration
   • Select your IdP type
   • Configure redirect URIs for MCP

2. MCP Configuration:

{
  "servers": {
    "faos": {
      "command": "faos-mcp",
      "env": {
        "FAOS_API_URL": "https://api.yourcompany.faosx.ai",
        "FAOS_AUTH_METHOD": "sso",
        "FAOS_SSO_DOMAIN": "yourcompany.com"
      }
    }
  }
}

3. First-Time Authentication:
   • When you first use a FAOS tool, a browser window opens
   • Complete SSO login via your IdP
   • Token is cached locally for subsequent requests

SSO Token Refresh

SSO tokens refresh automatically. To force re-authentication:

# Clear cached SSO token
faos-mcp auth clear

# Or delete cache file directly
rm ~/.faos/auth_cache.json

Service Account Authentication

For automated systems and CI/CD pipelines.

Creating a Service Account

1. Admin Portal: Settings → Service Accounts → Create
2. Configure:
   • Name: "CI/CD Pipeline"
   • Scopes: Minimum required for automation
   • IP Allowlist: Restrict to CI runner IPs (optional)

MCP Configuration for Service Account

{
  "servers": {
    "faos": {
      "command": "faos-mcp",
      "env": {
        "FAOS_API_URL": "https://api.faosx.ai",
        "FAOS_SERVICE_ACCOUNT_ID": "sa_abc123",
        "FAOS_SERVICE_ACCOUNT_SECRET": "secret_xyz789"
      }
    }
  }
}

Multi-Tenant Configuration

For users with access to multiple FAOS tenants:

{
  "servers": {
    "faos-prod": {
      "command": "faos-mcp",
      "env": {
        "FAOS_API_URL": "https://api.faosx.ai",
        "FAOS_API_TOKEN": "prod_token_here",
        "FAOS_TENANT_ID": "tenant-prod"
      }
    },
    "faos-staging": {
      "command": "faos-mcp",
      "env": {
        "FAOS_API_URL": "https://staging-api.faosx.ai",
        "FAOS_API_TOKEN": "staging_token_here",
        "FAOS_TENANT_ID": "tenant-staging"
      }
    }
  }
}

Usage:

"Using faos-prod, get the current sprint status" "Using faos-staging, run the code-review workflow"

Token Management

Viewing Active Tokens

In FAOS Portal: Settings → API Tokens → Active Tokens

Revoking Tokens

1. Navigate to Settings → API Tokens
2. Find the token to revoke
3. Click Revoke
4. Confirm action

cảnh báo

Revoked tokens are invalidated immediately. Claude Desktop will show authentication errors until a new token is configured.

Token Rotation

Best practice: Rotate tokens every 90 days.

1. Generate new token in portal
2. Update mcp.json with new token
3. Restart Claude Desktop
4. Verify tools work with: "List FAOS tools"
5. Revoke old token in portal

Security Best Practices

Do

• Use environment variables for tokens in shared environments
• Set appropriate token expiration dates
• Use minimal required scopes
• Rotate tokens regularly
• Revoke tokens when no longer needed
• Use SSO for enterprise deployments

Don't

• Commit tokens to version control
• Share tokens between users
• Use overly broad scopes
• Keep tokens after leaving a project
• Ignore token expiration warnings

Troubleshooting Authentication

"Authentication failed" (401)

Causes:

• Invalid or expired token
• Token revoked
• Wrong API URL

Solutions:

1. Verify token in portal (not expired/revoked)
2. Regenerate token
3. Check API URL matches your environment

"Insufficient permissions" (403)

Causes:

• Token missing required scopes
• Resource requires higher access level

Solutions:

1. Check required scopes in Tool Reference
2. Generate new token with correct scopes
3. Contact admin for enterprise permissions

SSO Login Loop

Causes:

• Browser cookie issues
• IdP misconfiguration

Solutions:

1. Clear browser cookies for IdP domain
2. Try incognito/private window
3. Verify SSO configuration in admin portal
4. Clear local auth cache: faos-mcp auth clear

Next Steps

• Tool Reference - Detailed tool documentation
• Enterprise Setup - Full enterprise deployment guide