Pages in this manual

For owners

For developers

About

For owners

Connect an AI tool

Connect an AI tool to Forge with its own sign-in or with an API key.

Any AI tool that supports MCP can connect to Forge. This page has the steps every tool shares.

Pages for particular tools

No tool has its own page yet. A tool gets one after Forge has connected it once and recorded how it went, so every step and picture on it is real. Until then, the steps below are the ones every tool shares.

What you need

  • Data access available for your company. It starts on; if someone turned it off, an owner or admin can enable it again in Settings.
  • To be an owner, admin, project manager or estimator of the company you want to connect. A project manager or estimator connects to read only, through the tools marked for them below, and sees only what Forge shows them in the app.
  • The connector address, which you paste into your AI tool: https://api.forge.equipment/mcp

Connect with the tool's own sign-in

  1. In your AI tool, add a custom connector and paste the connector address. Tools name this step differently, and some call it adding an MCP server.
  2. Start the connection from inside your AI tool, never from a link somebody sent you. The tool opens a Forge page in your browser.
  3. Check the page before you do anything else. The address bar shows app.forge.equipment, and the line "After you choose, you'll go back to" names the tool you started from. See how verification works.
  4. Sign in with your normal Forge login.
  5. Pick one company. Companies you cannot connect are greyed out with the reason, such as "Data access is off".
  6. Read what the tool can access. Leave the optional edit choice off for read access only, or select it after reviewing the listed changes. Then choose Allow read access or Allow read and edit access.
  7. Go back to your tool. It is connected. Forge tells you and the company owner by email, or by a push notification and a notice in Forge for anyone with no email address.

The connection is then listed in Forge, in Settings, for every owner and admin of the company, with when it was last used. If you choose Cancel instead, nothing is shared.

Use an API key instead

An API key works on both doors: the public API and the MCP server. It reads the same data through either one and can only read: an API key can never make changes. Its reads go into the same record, and revoking it stops it on both at once.

  • Keys are created only on the web, by an owner or admin, in Forge, in Settings. The Forge app on a phone lists keys and revokes them, but does not create them.
  • Forge shows a new key once. Copy it then. Every key starts with fgo_key_.
  • A tool that lets you add a header to its requests can use a key on the MCP server instead of signing in: send the header Authorization: Bearer followed by the key, to the connector address https://api.forge.equipment/mcp.
  • A key belongs to the person who created it, for one company. It stops working when that person leaves the company or stops being an owner or admin, when data access is turned off, or when any owner or admin revokes it. It does not expire on its own, so revoke a key nobody uses.
  • Anyone who has a key can read your company's data with it. Give it only to people and software you have chosen.

If you own more than one company

Each connection reads one company, the one you pick on the Forge page. To read a second company, connect again and pick the other company. If your AI tool will not add the same connector address twice, connect one company at a time: end the connection, then connect again and choose the other company.

Plans and organisations

  • Some AI tools allow only one custom connector on a free plan. If yours does and you already use one, remove it or change plans before you add Forge.
  • In an AI tool your organisation runs, only the organisation's owner may be able to add a connector. Ask them to add Forge. Adding it connects nobody's Forge company: each Forge person who uses it still signs in to Forge and approves the connection for their own company, and that connection belongs to them.

What your AI tool can ask Forge

These are the tools Forge offers an AI tool. The list is built from Forge's own tool list, so it matches what your tool is offered, and it marks any tool that is not open yet. Some tools only read. The ones marked as changes edit your company's records, and only for a connection an owner or admin allowed to make changes; an API key can never use them, and every change is recorded. See reads and edits.

find_jobs

Find jobs

Find the company's jobs by name or client text, stage, status or last update, or by the id another system holds for the job (externalSystem and externalId, as stored with link_external_id).

Owners, admins, project managers and estimators can use this tool. A project manager or estimator sees only what Forge shows them in the app.

What it takes

  • query string

    Text matched against the job name and the client's name.

  • stage one of presale, pre_construction, active, closed

    Only jobs at this stage.

  • status one of active, archived

    Only active or only archived jobs.

  • updatedSince date and time (ISO 8601)

    Only jobs updated at or after this time, as an ISO 8601 date-time.

  • externalSystem string

    With externalId: only the job linked to that id in this other system, named the way link_external_id stored it (lower case).

  • externalId string

    With externalSystem: the other system's job id.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

  • limit whole number, 1 to 100, default 20

    How many items to return: 20 by default, at most 100.

get_job

Get a job

Read one job: its summary, its current documents and their status labels, the project description and whether Forge or a person wrote it, the job type and permit flag from the current scope, hasScope (true once a person has confirmed the job's scope), the job's areas with their photo counts and trades, and one page of its photos.

Owners, admins, project managers and estimators can use this tool. A project manager or estimator sees only what Forge shows them in the app.

What it takes

  • jobId string, required

    The job's id.

  • photoCursor string

    The photos.nextCursor value from the previous page. Omit it to start at the beginning.

  • photoArea string

    Only photos filed to this area: its slug or its label, any case. Only photos that have been filed (by a person or the walk's area timeline) can match.

  • photoTrade string

    Only photos filed to this trade. Only photos that have been filed (by a person or the walk's area timeline) can match.

  • includeHidden true or false, default false

    Include photos a person hid. False by default.

list_estimates

List estimates

List the company's current estimates with their totals, for questions such as which jobs are waiting on an estimate.

Only an owner or admin connection can use this tool.

What it takes

  • status string

    Only estimates with this status label.

  • updatedSince date and time (ISO 8601)

    Only estimates updated at or after this time, as an ISO 8601 date-time.

  • view one of customer, internal, default customer

    customer (the default) or internal.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

  • limit whole number, 1 to 100, default 20

    How many items to return: 20 by default, at most 100.

get_estimate

Get an estimate or change order

Read one estimate, or one change order by its id, current version only: a header and the totals on every page, then one page of its lines.

Only an owner or admin connection can use this tool.

What it takes

  • documentId string, required

    The estimate or change order's id.

  • view one of customer, internal, default customer

    customer (the default) or internal.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

get_scope

Get a scope

Read one scope, a scope_meeting or a scope_document, current version only, section by section with every item.

Owners, admins, project managers and estimators can use this tool. A project manager or estimator sees only what Forge shows them in the app.

What it takes

  • documentId string, required

    The scope's id.

  • view one of customer, internal, default customer

    customer (the default) or internal.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

get_photo

Get a photo

Read one job photo as an image: the resized copy, at most 1568 pixels on its long edge and 1 MB, with a text block naming its id, job, source, caption, phase, when it was taken, and its walk, take, area and trades.

Owners, admins, project managers and estimators can use this tool. A project manager or estimator sees only what Forge shows them in the app.

What it takes

  • photoId string, required

    The photo's id.

  • includeHidden true or false, default false

    Include a photo a person hid. False by default.

list_walks

List walks and sweeps

List the company's walks and daily sweeps, or one job's, optionally between from and to: kind, the job or jobs covered, when recorded, walk type and job phase, the number of takes, length, whether each has a transcript, audio and video, and whether it has area chapters.

Owners, admins, project managers and estimators can use this tool. A project manager or estimator sees only what Forge shows them in the app.

What it takes

  • jobId string

    The job's id.

  • from date and time (ISO 8601)

    Only walks recorded at or after this time, as an ISO 8601 date-time.

  • to date and time (ISO 8601)

    Only walks recorded before this time, as an ISO 8601 date-time.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

  • limit whole number, 1 to 100, default 20

    How many items to return: 20 by default, at most 100.

get_transcript

Get a walk transcript

Read a walk's or sweep's transcript as time-stamped segments, in the shown language or the original.

Owners, admins, project managers and estimators can use this tool. A project manager or estimator sees only what Forge shows them in the app.

What it takes

  • walkId string, required

    The walk or sweep's id.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

  • takeId string

    The take's id.

  • fromSeconds number

    Start of the range, in seconds from the start of the take.

  • toSeconds number

    End of the range, in seconds from the start of the take.

  • language one of shown, original, default shown

    shown (the default) or original, for a translated walk.

get_rate_book

Get the company's rate book

Read the company's master rates: each rate's rateId, table, name, value exactly as stored, amount, the unit it is quoted per, its measurement basis when one is set, where it came from and when it last changed, and the id of any proposal waiting on it.

Only an owner or admin connection can use this tool.

What it takes

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

  • limit whole number, 1 to 100, default 20

    How many items to return: 20 by default, at most 100.

list_rate_proposals

List rate change proposals

List the company's proposed rate changes, newest first: the rate, its value when proposed, the proposed and the recommended amount, every comp with whether it was held out as an outlier and its recency weight, the status (pending, approved, rejected or reverted) and, once decided, when and what was applied.

Only an owner or admin connection can use this tool.

What it takes

  • status one of pending, approved, rejected, reverted

    Only proposals with this status.

  • cursor string

    The nextCursor value from the previous page. Omit it to start at the beginning.

  • limit whole number, 1 to 100, default 20

    How many items to return: 20 by default, at most 100.

update_job

Update a job's contact, address, stage or archive flag

Change a job's client contact (name, email, phone), its site address (street, city, state, zip), its stage (presale, pre_construction, active, closed) or whether it is archived.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • jobId string, required

    The job's id.

  • client object

    The client's contact details to change.

  • address object

    The job site address fields to change.

  • stage one of presale, pre_construction, active, closed

    Move the job to this stage.

  • archived true or false

    True archives a closed job; false unarchives it.

  • duplicateOfJobId string

    With archived true: the id of the live job this presale job duplicates. Lets a presale duplicate (no estimate sent, approved or sold) be archived.

  • dryRun true or false, default false

    True answers what would change and changes nothing. False by default.

update_sweep_segment

Update a daily sweep segment

Change one segment of a daily sweep, named by the segmentId get_transcript gives it: reassign it to another job, set its decision (proposed, confirmed or rejected), and mark it synced with the id of the object you made from it in another system.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • segmentId string, required

    The segment's id, from get_transcript on a sweep.

  • jobId string

    The job to reassign the segment to's id.

  • decision one of proposed, confirmed, rejected

    The segment's decision.

  • synced object

    Mark the segment synced with the object made from it in another system.

  • dryRun true or false, default false

    True answers what would change and changes nothing. False by default.

merge_jobs

Merge duplicate jobs

Fold duplicate jobs into the one you keep: their walks, sweep segments, photos and documents move to the kept job, their other-system ids move with them, and each duplicate is archived and marked merged into the kept job.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • keepJobId string, required

    The job to keep's id.

  • mergeJobIds array, required

    The duplicate jobs to fold into it, at most 10.

  • dryRun true or false, default true

    True (the default) answers what would change and changes nothing. Pass false to make the change.

record_estimate_outcome

Record an estimate's outcome

Record whether the company won or lost one of its estimates (or no decision was made), the day it was decided and why, for example after the proposal closed in the company's other system.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • estimateId string, required

    The estimate's id.

  • outcome one of won, lost, no_decision, required

    won, lost or no_decision.

  • decidedOn string, required

    The day it was decided, as YYYY-MM-DD.

  • reason value

  • dryRun true or false, default false

    True answers what would change and changes nothing. False by default.

record_sent_prices

Record the prices the contractor sent

Record the unit price the contractor actually sent the client for lines of one of the company's estimates, with any quantity or note correction, beside the price Forge generated.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • estimateId string, required

    The estimate's id.

  • lines array, required

    The lines, at most 200, each named by the lineId get_estimate gives it.

  • dryRun true or false, default false

    True answers what would change and changes nothing. False by default.

record_actual_costs

Record what the work actually cost

Record what work on one of the company's jobs actually cost, per estimate line (estimateId and lineId) or per cost code, as the company's books show it.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • jobId string, required

    The job's id.

  • costs array, required

    The costs, at most 200: each names an estimate line (estimateId and lineId) or a costCode, not both.

  • dryRun true or false, default false

    True answers what would change and changes nothing. False by default.

propose_rate_change

Queue a proposed rate for a person to approve

Queue a proposed new amount for one of the company's master rates, named by its rateId from get_rate_book, citing the comps behind it: the company's own recorded sent prices and actual costs (record_sent_prices, record_actual_costs), each named by its feedbackId or by its estimateId, lineId and source.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • rateId string, required

    The rate's id, from get_rate_book.

  • proposedRate number, required

    The amount you propose, in dollars per unit.

  • unit string, required

    The unit the rate is quoted per, which must be the rate's own.

  • comps array, required

    The comps, at most 50, each one of the company's own records. At least 3 different jobs must remain after outliers and old comps are held out.

  • rationale value

  • dryRun true or false, default false

    True answers what would change and changes nothing. False by default.

create_job

Create a job with its client and address

Create a job with its client and site address.

Only an owner or admin connection can use this tool.

Requires an owner or admin connection with edit permission. API keys cannot use this tool. Use dryRun to preview the changes; every applied change is recorded.

What it takes

  • name string, required

    The job's name, as it shows in Forge.

  • client object, required

    The job's client: matched to an existing client of the company, or created.

  • address object, required

    The job site address.

  • stage one of presale, pre_construction, active, closed, default presale

    The job's stage; presale by default.

  • description string

    A short description or scope note for the job.

  • externalLink object

    Another system's id for this job, stored on it at creation.

  • dryRun true or false, default true

    True (the default) answers what would change and changes nothing. Pass false to make the change.

Photos

get_photo returns a job photo itself, as a resized copy. Whether your AI tool then shows you the photo depends on the tool. This manual says a tool shows photos only after a real connection to that tool has shown one, on that tool's own page above.

Connect only tools you trust

Your AI tool reads what Forge returns word for word. That includes job names, notes, scopes, estimate notes and assumptions, and walk transcripts, and so it includes what your team, your subcontractors and your clients wrote or said.

Text like that can carry instructions meant for the AI tool, planted by anyone who can put words into those places. Forge cannot detect or remove them. Forge tells your tool that everything it returns is data, not instructions, but a tool may still act on what it reads, and most AI tools have other connections that can send email, change files or do other things.

So connect only tools you trust, and keep an eye on what they do with their other connections.