# Developers | Fieldmox API, MCP server and webhooks

> Connect AI assistants and your own code to Fieldmox: an MCP server with OAuth 2.1, agent sign-up, API keys and signed webhooks. Every call runs with the user's own permissions.

Source: https://www.fieldmox.com/developers

Developers

# Build on Fieldmox. Same rules as the app.

Connect an AI assistant, call Fieldmox from your own code, or get a webhook when something changes. Every request runs as a real user, in one team, with that user's permissions.

[Connect ChatGPT or Claude](https://www.fieldmox.com/integrations/chatgpt-claude) [Read auth.md](https://www.fieldmox.com/auth.md)

-   [
    
    ## MCP server
    
    For ChatGPT, Claude, Cursor and any MCP client. The user signs in through OAuth and picks the team the connection works in.
    
    ](#mcp)
-   [
    
    ## Agent sign-up
    
    For agents without a browser. The agent registers itself, sends the user a link and a code, and waits for them to approve it.
    
    ](#agent-auth)
-   [
    
    ## API keys
    
    For your own scripts and servers. An admin creates a key in Settings and your code sends it with each request.
    
    ](#api-keys)
-   [
    
    ## Webhooks
    
    Fieldmox calls your URL when a job, invoice, quote or client changes. Every delivery is signed.
    
    ](#webhooks)

## Endpoints

Everything runs on one API origin, `api.fieldmox.com`.

MCP server (Streamable HTTP)

`https://api.fieldmox.com/api/mcp` Copy

OAuth issuer

`https://api.fieldmox.com/api/auth` Copy

Protected resource metadata

`https://api.fieldmox.com/.well-known/oauth-protected-resource` Copy

Agent Auth discovery

`https://api.fieldmox.com/.well-known/agent-configuration` Copy

Health

`https://api.fieldmox.com/health` Copy

MCP server

## Give an AI assistant your jobs, quotes and invoices.

The Fieldmox MCP server speaks Streamable HTTP and uses OAuth 2.1. Clients register themselves with Dynamic Client Registration, and public clients with PKCE (S256) are accepted, so there's no client ID to request from us.

The user signs in during the OAuth redirect, or creates an account there. If they belong to more than one team, they pick one, and the token works in that team only.

Using ChatGPT or Claude? [Follow the setup guide](https://www.fieldmox.com/integrations/chatgpt-claude).

### Scopes

Scope

Grants

heffl:actions:read

Read tools

heffl:actions:write

Create, update and delete tools, within the user's role and approval rules

offline\_access

Refresh tokens, so the connection stays signed in

openid profile email

Who the user is

### What the tools cover

The tool list is built from the same actions the Fieldmox app uses. A tool only appears if the user's role allows it.

-   Field service
    
    Jobs, visits, properties and sites, tasks, and the timeline on any record.
    
-   Clients
    
    Companies and contacts, comments, tags, sources and service zones.
    
-   Sales
    
    Leads and lead stages, pipelines, quotations and lost reasons.
    
-   Money
    
    Invoices, payments received, products and tax rates.
    
-   Email and documents
    
    Send email, read email threads, and create documents from your templates.
    
-   Custom objects
    
    Any custom object your team has set up, with its own fields.
    

Four helper tools let an agent find its way: `heffl_search_actions`, `heffl_describe_action`, `heffl_validate_action` and `heffl_whoami`.

Every tool returns the same envelope:

```
{ "ok": true, "data": … }
{ "ok": false, "error": { "code": "…", "message": "…" } }
```

Agent sign-up

## For agents that run without a browser.

Fieldmox is an [Agent Auth Protocol](https://agentauthprotocol.com) provider. An agent registers with an Ed25519 key, asks only for the capabilities it needs, and gets back a link and a short code for the user.

The user opens the link, signs in or creates an account, checks the code matches, picks a team and approves. The agent can then call the same tools as the MCP server.

The user doesn't need a Fieldmox account beforehand. An agent can sign them up, but a person always approves it, and every account has a verified email.

1.  1
    
    Discover
    
    GET /.well-known/agent-configuration lists every endpoint and the supported key algorithm.
    
2.  2
    
    Register
    
    POST /api/auth/agent/register with a signed host JWT, the capabilities you want and the user's email.
    
3.  3
    
    Hand off
    
    Send the user the approval link and the XXXX-XXXX code. Never enter the code for them.
    
4.  4
    
    Call
    
    Once approved, POST /api/auth/capability/execute with a short-lived agent JWT.
    
5.  The full flow, with request examples and error handling, is in [auth.md](https://www.fieldmox.com/auth.md).

API keys

## Call Fieldmox from your own code.

An admin creates a key in **Settings → Developer**. Fieldmox shows the key once, so store it somewhere safe. Send it in the `x-api-key` header.

A key reaches the same actions as the MCP server. List them from the catalog, then invoke one by name with its input.

API keys and webhooks are included in the [Unlimited plan](https://www.fieldmox.com/pricing).

```
# What can this key do?
curl https://api.fieldmox.com/api/actions/catalog \
  -H "x-api-key: $FIELDMOX_API_KEY"

# Run one action
curl https://api.fieldmox.com/api/actions/leads.create/invoke \
  -H "x-api-key: $FIELDMOX_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "input": { … } }'
```

`GET /api/actions/catalog/{name}` returns one action's input schema. Results use the same `ok` / `error` envelope as MCP.

Webhooks

## Hear about changes the moment they happen.

Add a webhook in **Settings → Developer**, choose the events you want, and use **Test** to send a sample delivery.

Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) spec. Each one carries `webhook-id`, `webhook-timestamp` and `webhook-signature` headers, signed with HMAC-SHA256 using your `whsec_` secret. Any Standard Webhooks library can verify them.

### Events

Leads

-   lead.created
-   lead.updated
-   lead.deleted
-   lead.stageChanged

Deals

-   deal.created
-   deal.updated
-   deal.deleted
-   deal.stageChanged

Contacts

-   contact.created
-   contact.updated
-   contact.deleted
-   contact.stageChanged

Companies

-   company.created
-   company.updated
-   company.deleted
-   company.stageChanged

Quotations

-   quotation.created
-   quotation.updated
-   quotation.deleted
-   quotation.statusChanged

Jobs

-   job.created
-   job.updated
-   job.deleted
-   job.statusChanged

Invoices

-   invoice.created
-   invoice.updated
-   invoice.deleted
-   invoice.statusChanged
-   invoice.paid

Payments and forms

-   payment.received
-   form.response.created

## For agents reading this page

Machine-readable descriptions of everything above. Every page on this site also has a markdown version, served when you request it with `Accept: text/markdown`.

-   [auth.md, the step-by-step sign-up guide for agents auth.md](https://www.fieldmox.com/auth.md)
-   [MCP server card server-card.json](https://www.fieldmox.com/.well-known/mcp/server-card.json)
-   [API catalog (RFC 9727) api-catalog](https://www.fieldmox.com/.well-known/api-catalog)
-   [AI catalog ai-catalog.json](https://www.fieldmox.com/.well-known/ai-catalog.json)
-   [Agent skills index.json](https://www.fieldmox.com/.well-known/agent-skills/index.json)
-   [llms.txt llms.txt](https://www.fieldmox.com/llms.txt)

![Mox on site, checking equipment and logging it on his phone](https://www.fieldmox.com/mascot/station.webp)

## Building something on Fieldmox?

Tell us what you're making. The people who build the API answer, and we'd like to hear what's missing.

[Email the team](mailto:support@heffl.com?subject=Fieldmox%20API) [Create an account](https://app.fieldmox.com/signup)
