Skip to main content

​
Prerequisites

  • Python 3.11 or later
  • uv (recommended) or pip
  • Node.js / npm (optional) — Useful if your MCP target is an npm package you spawn locally
  • LLM provider API key (optional) — Only needed if a library workflow or fixture uses a model. Store credentials in the OS keyring via ctpf config set-credential. See Configure a provider.

​
Install

pip install ctpf

git clone https://github.com/q-uestionable-AI/CTPF.git
cd CTPF
uv sync --group dev
Confirm the CLI: 
ctpf --help
ctpf --version
The former qai executable remains available as a compatibility alias for ctpf. Existing q-uestionable-ai installations upgrade through a same-version compatibility package.

​
Configure a provider (optional)

Provider credentials are optional for the core proxy / targets workflow. If a library fixture needs a model, store the API key in the OS keyring (never in config files): 
ctpf config set-credential anthropic
# Prompts for your API key (masked input)

ctpf config set-credential openai

ctpf config set-credential <provider-name>

ctpf config list-providers
When selecting a model elsewhere, use the provider/model format (e.g., anthropic/claude-sonnet-4-20250514).

​
Register a target and start the proxy

1

Register an MCP target

Point CTPF Research Harness at a server you are authorized to test:
ctpf targets add "My Server" http://localhost:3000/sse
ctpf targets list
Transports include stdio (command string), SSE, and Streamable HTTP. See Targets and Transports.
2

Start the proxy

The proxy is the CTPF observation center — capture, optional intercept (forward / modify / drop), and session export:
ctpf proxy --help
Configure the MCP client you control to connect through the proxy instead of directly to the target. See Proxy Overview.
3

Inspect local state

Runs and findings live in SQLite (~/.qai/qai.db):
ctpf runs list
ctpf findings list
ctpf db --help

​
Library tooling (not root CLI pillars)

Audit, inject, IPI, and CXP are libraries / research fixtures, not public ctpf subcommands after Phase 1. Examples: 
# Inject fixture server
python -m q_ai.inject serve --transport stdio

# IPI headless callback listener / generators
python -m q_ai.ipi --help

# Audit as a library (import or module entry — not `ctpf audit`)
python -c "import q_ai.audit; print('audit library available')"
See Audit Overview, Inject Overview, IPI Overview, and CXP Overview.

​
Next steps

Only test systems you own, control, or have explicit written authorization to test.