factors-mcp-v2 0.1.0

Factors.ai MCP server — agent management and execution tools

factors-mcp-v2

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)

Install

From the wheel (built locally)

cd factors_mcp_v2
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install dist/factors_mcp_v2-0.1.0-py3-none-any.whl

(Replace the wheel filename with the version produced under dist/.)

Editable install (development)

cd factors_mcp_v2
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

The factors-mcp-v2 console script is installed on your PATH.

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-v2, 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": "/absolute/path/to/your/.venv/bin/python",
      "args": ["-m", "factors_mcp_v2"],
      "env": {
        "FACTORS_API_KEY": "your_private_token",
        "FACTORS_API_URL": "https://api.factors.ai"
      }
    }
  }
}

Alternatively, if factors-mcp-v2 is on your PATH inside that venv:

{
  "mcpServers": {
    "factors-ai": {
      "command": "/absolute/path/to/your/.venv/bin/factors-mcp-v2",
      "args": [],
      "env": {
        "FACTORS_API_KEY": "your_private_token",
        "FACTORS_API_URL": "https://api.factors.ai"
      }
    }
  }
}

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": "/absolute/path/to/your/.venv/bin/python",
      "args": ["-m", "factors_mcp_v2"],
      "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-v2 so the client does not pick up a different interpreter than the one where the package is installed.

Build the wheel

From this directory (factors_mcp_v2):

python -m venv .venv
source .venv/bin/activate
pip install build
python -m build

Artifacts appear under dist/:

• factors_mcp_v2-<version>-py3-none-any.whl
• factors_mcp_v2-<version>.tar.gz (sdist)

Run the MCP server

1. After installing the package (recommended)

export FACTORS_API_KEY=your_private_token
export FACTORS_API_URL=https://api.factors.ai   # optional; default shown

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

Or:

python -m factors_mcp_v2

2. SSE over HTTP (remote / Docker-style)

The underlying FastMCP server supports transport="sse". Set env vars and use the entry point; if you need SSE explicitly, run the same module with a small wrapper or extend main() in server.py to pass transport="sse" and host/port as needed.

For local Docker builds, the repo may use a Dockerfile that sets FASTMCP_HOST / FASTMCP_PORT and runs the server.

3. Run from the repo without installing (development only)

You must put the package on PYTHONPATH so factors_mcp_v2 imports resolve:

cd factors_mcp_v2
export PYTHONPATH=src
export FACTORS_API_KEY=your_private_token
python src/factors_mcp_v2/server.py

Prefer pip install -e . and factors-mcp-v2 or python -m factors_mcp_v2 instead.

Environment variables

Variable	Default	Purpose
FACTORS_API_KEY	(required)	Private project token (Authorization header to /mcp/afx/*)
FACTORS_API_URL	https://api.factors.ai	Base URL of the Factors API
FACTORS_BEARER_TOKEN	(empty)	Optional; reserved for future use
FACTORS_SESSION_TOKEN	(empty)	Optional session-related env

Package layout

factors_mcp_v2/
  pyproject.toml
  README.md
  requirements.txt
  src/
    factors_mcp_v2/
      __init__.py
      __main__.py
      server.py          # MCP server (FastMCP tools, resources, prompts)
      utils.py
      AGENT_PROMPT_GUIDELINES.md

License

Proprietary — Factors.ai internal use unless otherwise stated.