Connect an AI assistant (MCP)

Connect FOREMAN to an AI assistant like Claude or ChatGPT and work your site data in plain English — "how many hours did Jamie log on Hawthorn this fortnight?", "create a task for Sam on Brunswick", "build me a SWMS template with these fields" — instead of aggregating and clicking by hand.

The simple way (point-and-click)

Best for Claude Desktop, claude.ai, and ChatGPT — no files, no commands.

Claude Desktop or claude.ai

1. Open Settings → Connectors → Add custom connector.
2. Paste the FOREMAN server address:

   https://app.foremanapp.com.au/api/mcp

3. Click Add. Claude opens a FOREMAN sign-in in your browser — sign in (or sign up), then approve the one-tap Allow screen. Claude stores the connection; there's no key to copy.

That's it — Claude can now see your FOREMAN sites. The Free plan allows one connector.

ChatGPT

Remote connectors need a paid ChatGPT plan with Developer mode turned on (if you want the easiest route, Claude Desktop is simpler):

1. Settings → Apps & Connectors → Advanced settings → turn on Developer mode.
2. Settings → Connectors → Create. Name it Foreman and set the Connector URL to https://app.foremanapp.com.au/api/mcp.
3. Approve the sign-in, then enable it in a conversation.

What the assistant can do

Once connected, it acts as an Admin across your whole workspace (your "tenant" — your company's private FOREMAN data). It can:

• Read everything — projects, tasks, crew, diary entries, project photos (diary + standalone), form submissions, and the induction register. list_project_photos returns a page at a time — 48 photos by default, plus a hasMore flag; the assistant fetches the rest by advancing offset.
• Create, edit, and delete projects, tasks, and form templates.
• Manage crew and users, log diary entries, upload documents, diary photos, and standalone project photos (attached straight to a project, no diary entry), edit induction content, and fetch document download links. An attached photo can carry an originalFilename alongside its path, which becomes the name it downloads as. Photos must be 2 MB or smaller — Storage rejects a larger upload at the PUT step, so resize first (1600px on the long edge is plenty).
• Organise documents into folders (list_document_folders, create_document_folder) and file a document into one as you upload it. Folders are one level deep and never change who can see a document.
• Read and update your business profile — name, website, and timezone (get_business_profile, update_business_profile).
• Set your business logo — request_business_logo_upload → PUT the image → set_business_logo (or remove_business_logo), the same two-step flow as documents. PNG/JPG/SVG up to 5 MB.

See the full tool list in the API reference.

Developer setup

For coding tools. The server is a remote Streamable HTTP MCP endpoint:

https://app.foremanapp.com.au/api/mcp

Authenticate either with OAuth (a browser approval) or with your tenant API key as an Authorization: Bearer header.

Claude Code

Add the server, then authenticate in the browser with OAuth:

claude mcp add --transport http foreman https://app.foremanapp.com.au/api/mcp

Inside a session, run /mcp and approve the browser prompt. Tokens are stored in your system keychain and refreshed automatically.

No account yet? Just ask Claude Code to sign you up — "Sign me up for FOREMAN, my email is me@example.com, business name Acme Builders." It calls POST /api/v1/signup (see Sign up), gets a working key back immediately, installs it as this server's Authorization: Bearer header, and reconnects — no browser step.

Prefer to use your API key instead of OAuth? Pass it as a header — but don't do both, since a rejected header won't fall back to OAuth:

claude mcp add --transport http foreman https://app.foremanapp.com.au/api/mcp \
  --header "Authorization: Bearer YOUR_FOREMAN_API_KEY"

Add --scope project to share it with your team via a checked-in .mcp.json, or --scope user to use it across all your projects (the default is this project only).

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (this project):

{
  "mcpServers": {
    "foreman": {
      "url": "https://app.foremanapp.com.au/api/mcp"
    }
  }
}

Cursor runs the OAuth flow automatically on first use. To use your API key instead, add a header (${env:VAR} expansion is supported):

{
  "mcpServers": {
    "foreman": {
      "url": "https://app.foremanapp.com.au/api/mcp",
      "headers": { "Authorization": "Bearer ${env:FOREMAN_API_KEY}" }
    }
  }
}

Or one-click: Add to Cursor.

VS Code

Add to .vscode/mcp.json (workspace). Note VS Code uses servers (not mcpServers) and requires "type": "http":

{
  "servers": {
    "foreman": {
      "type": "http",
      "url": "https://app.foremanapp.com.au/api/mcp"
    }
  }
}

To authenticate with your API key, prompt for it securely with an input so it's never stored in plain text:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "foreman-api-key",
      "description": "FOREMAN API key",
      "password": true
    }
  ],
  "servers": {
    "foreman": {
      "type": "http",
      "url": "https://app.foremanapp.com.au/api/mcp",
      "headers": { "Authorization": "Bearer ${input:foreman-api-key}" }
    }
  }
}

Or run MCP: Add Server from the Command Palette and follow the guided flow.

Older Claude Desktop builds

If your Claude Desktop is too old for the custom-connector UI, bridge it with mcp-remote in claude_desktop_config.json, then restart Claude Desktop fully:

{
  "mcpServers": {
    "foreman": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.foremanapp.com.au/api/mcp"]
    }
  }
}

Other clients

Any client that supports remote Streamable HTTP MCP servers works — point it at https://app.foremanapp.com.au/api/mcp and authenticate with OAuth or an Authorization: Bearer <API key> header.

Access, billing & revoking

• Scope — every connection acts with Admin-equivalent, tenant-wide access; it only ever sees your own tenant's data.
• Revoking — disconnect in your client (remove the connector in a GUI client, or /mcp → clear authentication in Claude Code), or rotate your API key in Settings → API & integrations. OAuth sessions can also be revoked from Settings.
• Billing — while a subscription is cancelled, read tools keep working and write tools return a clear "subscription inactive" message.

Troubleshooting

• Connector is added but every tool says "requires authentication" — you haven't finished the browser sign-in (you may have closed it before approving). Open Settings → Connectors → FOREMAN and use Connect / authenticate to complete the one-tap browser approval.
• Tools don't appear / connection failed (Claude Code) — you configured an Authorization header and it was rejected; Claude Code does not fall back to OAuth. Fix the key, or drop the header to use OAuth via /mcp.
• Config-file changes don't take effect — restart the client. Claude Desktop and VS Code re-read MCP config on restart.
• A cloud client can't reach a local server — not an issue here: FOREMAN is publicly hosted, so Claude Desktop and ChatGPT reach it from their cloud.
• Write tools return "subscription inactive" — the tenant's subscription is cancelled; reads still work. Reactivate from Settings → Billing.

Prefer raw HTTP? Everything here is also available over the public API with your tenant API key.