AroFlo MCP

Standalone, production-ready MCP server for AroFlo with first-class request signing and a clean tool surface.

Quick Start

Install (Local)

This repo ships an MCP server executable named aroflo-mcp (stdio transport by default).

Install the server on your machine (puts aroflo-mcp on your PATH via npm link):

Install Into Codex (stdio)

1. Create a local .env (not committed) with your credentials:

2. Register the server in Codex (stores env in ~/.codex/config.toml, not passed as tool args):

3. Verify:

Manual Codex Install (Alternative)

If you prefer doing it manually (same env variables, stored in Codex config):

Notes:

• If Codex (desktop app) hangs starting the server, it is usually a PATH issue (common when Node is installed via nvm and the app is launched outside your shell).

• Fix 1: Launch Codex from a terminal so it inherits your shell PATH (codex app).

• Fix 2: Configure the MCP server to run via an absolute Node path (see docs/runbooks.md).

Development

Install dependencies:

Build and test:

Run server (stdio):

Run server (HTTP Streamable transport):

MCP Inspector

To interactively test tools/list and tools/call via the official inspector UI:

Project Layout

Environment

Required variables:

• AROFLO_SECRET_KEY

• AROFLO_UENCODED

• AROFLO_PENCODED

• AROFLO_ORG_ENCODED

Optional variables:

• AROFLO_API_BASE_URL (default: https://api.aroflo.com/)

• AROFLO_ACCEPT (default: text/json)

• AROFLO_HOST_IP

• AROFLO_TIMEOUT_MS (default: 65000)

• AROFLO_MAX_RETRIES (default: 2)

• LOG_LEVEL (default: info)

HTTP Transport

Set MCP_TRANSPORT=http to run an HTTP server (Streamable HTTP transport) at:

• http://${MCP_HTTP_HOST}:${MCP_HTTP_PORT}${MCP_HTTP_PATH}

Using Extracted API Docs (docs/api)

This repo includes a local snapshot of the AroFlo API docs in docs/api/.

The MCP server exposes these markdown files as MCP resources so the client/LLM can look up valid WHERE fields, JOIN areas, etc:

• aroflo://docs/api -> docs/api/README.md

• aroflo://docs/api/<slug> -> docs/api/<slug>.md (example: aroflo://docs/api/quotes)

Example query: list Quotes with acceptance status "Awaiting Decision":

• Tool: aroflo_get_quotes

• Args:

Example report: open projects with labour hours per task (recommended for progress reporting):

• Tool: aroflo_report_open_projects_with_task_hours

• Args (add optional filters like sinceDateRequested to keep outputs small):

Docs

• docs/aroflo-auth.md

• docs/mcp-tools.md

• docs/examples.md

• docs/runbooks.md

• docs/deployment.md

• docs/api/*