factors-mcp 0.1.2

Factors.ai MCP server — agent management and execution tools

factors-mcp

Python package exposing a Model Context Protocol (MCP) server for Factors.ai — list/create/update agents, run agents against domains, and use bundled prompt guidelines.

Requirements

• Python 3.10+
• A Factors private API token (FACTORS_API_KEY) with access to the Factors API (FACTORS_API_URL)

Environment variables

Variable	Default	Purpose
FACTORS_API_KEY	(required)	Private API token for Factors API calls
FACTORS_API_URL	https://api.factors.ai	Factors API base URL
FACTORS_HTTP_TIMEOUT_SECONDS	30	HTTP timeout (seconds) for all tool calls except run_agent

run_agent always uses a 300s HTTP timeout because agent runs can take several minutes.

Client configuration (Claude Desktop & Cursor)

Both clients drive the server over stdio. Point them at the Python interpreter or console script from the same virtualenv where you installed factors-mcp, and pass your API credentials in env (do not commit real keys into shared project files).

Claude Desktop

1. Quit Claude Desktop completely.
2. Open the config file in a text editor:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Merge the mcpServers entry below with any existing mcpServers object (do not remove other servers).

{
  "mcpServers": {
    "factors-ai": {
      "command": "python3",
      "args": ["-m", "factors-mcp"],
      "env": {
        "FACTORS_API_KEY": "your_private_token"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

1. Create or edit an MCP config file (JSON):
   • Project: <repo-root>/.cursor/mcp.json (optional; share with the team without secrets)
   • User-wide: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)
2. Add a mcpServers entry (merge with existing servers if the file already exists).

{
  "mcpServers": {
    "factors-ai": {
      "command": "python3",
      "args": ["-m", "factors_mcp"],
      "env": {
        "FACTORS_API_KEY": "your_private_token",
        "FACTORS_API_URL": "https://api.factors.ai"
      }
    }
  }
}

Fully restart Cursor after changing MCP configuration so it reloads the server list.

Tip: Use absolute paths to python or factors-mcp so the client does not pick up a different interpreter than the one where the package is installed.

Run the MCP server

1. After installing the package (recommended)

export FACTORS_API_KEY=your_private_token 

# Default transport is stdio (typical for Cursor / Claude Desktop)
factors-mcp

Or:

python3 -m factors_mcp

0.1.2

• Major bug fixes

License

Proprietary — Factors.ai internal use unless otherwise stated.