MCP server

The Fictix backend includes fictix_mcp, an MCP server that adapts the Fictix API into tools, resources, and prompts an MCP-aware agent can call directly, instead of the agent hand-rolling curl calls from AGENTS.md. It's a companion to the project-file snippets on AI agent integration — use those if you just want an AGENTS.md/skill file, use this if your client speaks MCP.

Download the standalone MCP adapter. It installs independently of the backend repository and includes the public API guides. Use a company you create in Console and its normal API key. Native and execute tools retain the API's plan and scope restrictions.

Never put FICTIX_PROJECT_API_KEY or any other Fictix credential in browser JavaScript or commit it to a repo. Configure the server with environment variables and keep it running server-side or on your own machine, the same as any other project API key.

What it exposes

Tools that wrap the REST surface — reading entities and pages, discovering the catalog, and creating/controlling demo jobs.
Resources for pulling Fictix data (an entity page, a catalog listing) into an agent's context without a manual tool call.
Prompts that package common Fictix tasks — for example, loading a generated company into a target app — into a reusable starting point.
Read/write safeguards: read-only tools operate under the same project-scoped X-API-Key as the REST routes they wrap. Tools that create or control a company follow the same rules as POST /api/v1/demo-jobs directly — approved control-plane access (FICTIX_ADMIN_API_KEY, see below) and a stable Idempotency-Key — so running the server doesn't by itself grant write access you don't already have.

Install and run

Use Python 3.12 or later in a dedicated environment:

python3.12 -m venv .venv
.venv/bin/python -m pip install https://fictix-docs.vercel.app/downloads/fictix-mcp-0.1.1.zip
.venv/bin/python -m fictix_mcp --help

The archive manifest lists its SHA-256 and reviewed source files. This direct download is the supported installer; there is no PyPI or npm registry release yet. Do not substitute pip install fictix-mcp, uvx fictix-mcp, or npx fictix-mcp.

After configuring the three environment variables below, run:

.venv/bin/python -m fictix_mcp

stdio is the default transport. Your MCP client spawns the process and talks through stdin/stdout. Use the absolute path to this environment's Python in client configuration; a bare python can select an environment without the adapter. On Windows, the environment's executable is .venv\Scripts\python.exe.

Start with project_info, then browse_entity with entity="bills", limit=25, and offset=0. Page until the returned count is exhausted. The fictix://docs/quickstart resource and search_docs work from bundled public documentation, without a backend checkout.

Streamable HTTP and SSE are optional local transports: --transport streamable-http or --transport sse, with --host and --port. Keep the default loopback host unless you have configured access control for other clients.

Configure

fictix_mcp reads its own environment variable names — they are not the FICTIX_API_ORIGIN/FICTIX_PROJECT_SLUG shell conventions the curl examples elsewhere in these docs use. The values are the same ones, from the same place — your project's Connect to your builder panel in the Fictix Console — but the server only reads these names:

FICTIX_BASE_URL          # API origin, e.g. https://api.fictix.ai or https://api-staging.fictix.ai
FICTIX_DEFAULT_SLUG      # project slug, from Console > Connect to your builder
FICTIX_PROJECT_API_KEY   # from Console > Company settings > Company API keys

One optional variable enables the management tools (creating or controlling companies via demo jobs). It is for Fictix-approved server-to-server integrations only — a normal Console customer does not have it and cannot self-serve it:

FICTIX_ADMIN_API_KEY     # approved management key, sent as X-Admin-Key

The signed-in Console uses a managed WorkOS bearer session for its own management actions. That session is not available as a copyable MCP credential; external server-to-server MCP management uses the Fictix-supplied FICTIX_ADMIN_API_KEY only.

If it is not set, the read-only tools still work under the project API key — management tool calls go out uncredentialed and come back with the same 401 that POST /api/v1/demo-jobs itself returns.

Client config

Claude Code

claude mcp add fictix \
  -e FICTIX_BASE_URL=https://api.fictix.ai \
  -e FICTIX_DEFAULT_SLUG=<your-project-slug> \
  -e FICTIX_PROJECT_API_KEY=<your-project-api-key> \
  -- /absolute/path/to/.venv/bin/python -m fictix_mcp

Codex

Add a [mcp_servers.fictix] block to ~/.codex/config.toml:

[mcp_servers.fictix]
command = "/absolute/path/to/.venv/bin/python"
args = ["-m", "fictix_mcp"]
env = { FICTIX_BASE_URL = "https://api.fictix.ai", FICTIX_DEFAULT_SLUG = "<your-project-slug>", FICTIX_PROJECT_API_KEY = "<your-project-api-key>" }

See the official Codex MCP configuration reference for command and environment settings.

Cursor

Add a .cursor/mcp.json in your project (or user config directory):

{
  "mcpServers": {
    "fictix": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "fictix_mcp"],
      "env": {
        "FICTIX_BASE_URL": "https://api.fictix.ai",
        "FICTIX_DEFAULT_SLUG": "<your-project-slug>",
        "FICTIX_PROJECT_API_KEY": "<your-project-api-key>"
      }
    }
  }
}

Sidecar today, not a hosted endpoint

fictix_mcp is a process your agent (or you) run locally or on your own infrastructure — there is no hosted mcp.fictix.ai-style endpoint to point a client at instead. If your workflow needs a shared, always-on MCP endpoint rather than a per-developer local process, that's a gap worth raising with your Fictix contact; it isn't available yet.

Consuming these docs

Skill pack