> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forge integration reference

> Authentication, API conventions, OpenAPI, MCP, client choices, errors, and operation reference.

Use this section after choosing an interface. For exact HTTP request and response fields, the
generated operation pages and OpenAPI documents are authoritative.

## HTTP API

* **Production origin:** `https://api.forge.gloo.com`
* **Primary paths:** `/api/v3/...`
* **Authentication:** `Authorization: Bearer <credential>`
* **Success:** `{ data, meta }`
* **Application error:** `{ error, meta }`

API v3 is a resource-oriented mapping onto the same operations served under `/api/v2`. Each
generated operation page renders the v3 method and path while retaining the operation identity that
ties it to the source contract. Use v3 in new examples; use the operation page to confirm
validators, permission, credential kinds, idempotency, and responses.

Start with [Conventions](https://docs.gloo.com/forge/reference/conventions.md), [Errors](https://docs.gloo.com/forge/reference/errors.md), and
[Idempotency](https://docs.gloo.com/forge/reference/idempotency.md).

## Authentication and authorization

External Apps mint short-lived tokens at `/oauth/token`. Personal keys act as their owner only on
operations that accept that credential kind. Roles and scoped grants establish authority; token
scopes only narrow it. Runtime policy and resource reach can still refuse an otherwise valid actor.

Read [Credentials and access](https://docs.gloo.com/forge/get-started/credentials-and-access.md),
[Permissions](https://docs.gloo.com/forge/reference/permissions), and [Credential kinds](https://docs.gloo.com/forge/reference/credential-kinds.md).

## Pagination and bounded results

List operations return paging metadata. Continue with `meta.nextCursor` while `meta.hasMore` is
true. Treat `partial`, `truncated`, or an omitted large field as an explicit incomplete result;
follow the documented continuation rather than assuming the first response is complete.

## Contract sources

* [OpenAPI v3 JSON](https://docs.gloo.com/forge/reference/openapi-v3.json) for resource-oriented paths.
* [OpenAPI v2 JSON](https://docs.gloo.com/forge/reference/openapi.json) for operation identities used by generated pages
  and MCP operation discovery.
* [HTTP API reference](https://docs.gloo.com/forge/reference/http-api.md) for every operation, grouped by family.
* [Outcomes](https://docs.gloo.com/forge/concepts/outcomes.md) for workflow completion evidence.

## MCP

MCP provides common task tools, searchable operation discovery, resources, and prompts for AI
hosts. It is not an exhaustive named-tool mirror of the HTTP API. Read [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md)
or [connect a host](https://docs.gloo.com/forge/quickstart/mcp-host.md).

## Client choices

| Client | Status and boundary |
| - | - |
| Native HTTP | Recommended public integration contract |
| `@tangogroup/forge-mcp` | Current MCP server and local stdio package |
| TypeScript SDK | Legacy; migrate to native HTTP |
| Procedure SDKs | Available only inside Forge procedure sandboxes |

Read [Choose an interface](https://docs.gloo.com/forge/get-started/choose-an-interface.md),
[Node procedure SDK](https://docs.gloo.com/forge/reference/procedure-sdk-node.md),
and [Python procedure SDK](https://docs.gloo.com/forge/reference/procedure-sdk-python.md).

## Integration checklist

* Use a distinct actor and minimal roles/scopes.
* Persist stable idempotency keys for logical write intents.
* Handle non-JSON gateway failures and unknown write outcomes.
* Log `meta.requestId` without logging credentials or sensitive bodies.
* Follow cursors and bounded-result metadata.
* Test `401`, `403`, `409`, `429`, provider failure, and timeout behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.