ff-crm-mcp

Two commands for a CRM MCP gateway:

• ff-crm-mcp — one-shot CLI: open an MCP session, run one tool, exit.

• ff-crm-mcp-stdio — stdio↔Streamable-HTTP bridge, so the gateway can be registered as an MCP connector.

Stdlib only. No Node, no PyPI dependencies, Python 3.9+.

Install

--python 3.12 matters: on a machine with no Python at all, uvx otherwise fails with Failed to spawn: python.

# no git, no package index — straight from a release asset
uvx --python 3.12 --from https://github.com/AlexWolfGoncharov/ff-crm-mcp/releases/download/v0.1.0/ff_crm_mcp-0.1.0-py3-none-any.whl ff-crm-mcp --doctor

# from source, where git is available
uvx --python 3.12 --from git+https://github.com/AlexWolfGoncharov/ff-crm-mcp ff-crm-mcp-stdio

Related MCP server: iikona-mcp-proxy

The package ships code only

No gateway URLs, no hostnames, no market data. The endpoint always comes from you:

export CRM_MCP_URL="https://<gateway>/receiver-crm/mcp"
ff-crm-mcp --list-tools
ff-crm-mcp --doctor

Some gateways present a certificate that does not cover their host. For those, and only those, add CRM_MCP_INSECURE_TLS=1 (or --insecure).

If you have a markets.json, point at it and use --market/--env instead:

export CRM_MCP_MARKETS=/path/to/markets.json
ff-crm-mcp --market in --env prod --doctor

Resolution order: --url → CRM_MCP_URL → --market/--env via markets.json.

As a connector

One entry per market and env — the name is how you (and an agent) know which environment a call is writing to:

"crm-az-prod": {
  "command": "uvx",
  "args": ["--python", "3.12", "--from", "https://github.com/AlexWolfGoncharov/ff-crm-mcp/releases/download/v0.1.0/ff_crm_mcp-0.1.0-py3-none-any.whl", "ff-crm-mcp-stdio"],
  "env": {
    "CRM_MCP_URL": "https://<gateway>/receiver-crm/mcp",
    "CRM_MCP_INSECURE_TLS": "1"
  }
}

Restart the client afterwards; MCP servers are read at startup. The bridge prints the resolved URL to stderr on start, so the client log shows whether it reached the network.

On Windows, never use command: npx in a connector entry or an .mcpb manifest: it cannot spawn npx.cmd without a shell and dies with ENOENT. uvx has no such problem.

Diagnostics

ff-crm-mcp --doctor resolves the host through getaddrinfo, opens TCP 443, then runs a real initialize + tools/list and reports the tool count. Use it before blaming a gateway.

If the gateway is on a private network, note that nslookup and dig read /etc/resolv.conf and bypass the macOS scoped resolver — they report NXDOMAIN for hosts that applications resolve fine. --doctor uses getaddrinfo, which is what a real client does.

Guard rails

ff-crm-mcp refuses to create a communication that is not paused, refuses a promotional one without a control group, and refuses a destructive call without an explicit confirmation flag.

A connector enforces none of that — the bridge is transport only. Prefer the CLI wherever a shell is available.

Quirks it handles

• A certificate that does not cover the gateway host. --insecure / CRM_MCP_INSECURE_TLS=1 for exactly those endpoints.

• A gateway that echoes a numeric JSON-RPC id back as a string ({"id": 1} → {"id": "1"}). A strict client never matches that reply to its request; the bridge restores the original id and its type.