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, then Connect and approve the sign-in in your browser — a one-tap "Allow" screen, no password 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, form submissions, and the induction register.
• Create, edit, and delete projects, tasks, and form templates.
• Manage crew and users, log diary entries, upload documents and photos, edit induction content, and fetch document download links.

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 the sign_up tool (see Sign up), gets a working key back immediately, installs it as this server's auth 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

• 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.