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

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# AI providers and execution funding

> Configure authorized model funding and connect your own provider accounts with consent.

<Info>Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).</Info>

Melso authentication and model funding are separate. A Melso credential authorizes the API call; Melso credits, a provider API key or your own connected subscription account pays for execution. Manage personal funding in **Settings → AI providers**. The [execution funding reference](/api-reference/tags/execution-funding) owns the request and response schemas.

The [first MCP read](/mcp/connect#try-a-first-read) starts no Run and needs no Task execution funding. Configure funding before requesting execution; reading company context or discovering a catalog does not start it.

## Authentication

Follow [Authentication](/api-reference/authentication) for credential and company scopes. Run tokens and MCP OAuth grants cannot administer provider accounts or funding policies.

Both company-key scopes can read and update their own policy through `GET /api/provider-accounts/harnesses` and `PUT /api/provider-accounts/harnesses/{harness}`. A key has its own integration identity. Its policy uses Melso credits or its saved provider API key; `accounts_enabled` must be false for an ordinary key identity because it cannot borrow a member's subscription account.

A `tasks` key cannot administer provider accounts. An `admin` key can use its permitted account routes, but without a managed execution identity its account list is empty and starting a subscription connection returns `403 provider_account_workspace_key`. Managed customer funding is described below. Personal account management requires your signed-in session or personal token and access to the company and account.

## Connect an account

<Steps>
  <Step title="Choose your funding">
    Open **Settings → AI providers** and choose the provider or funding method available for your harness.
  </Step>

  <Step title="Complete consent">
    Connect your own account and complete the provider's authorization flow. A returned authorization link or pending session is not proof that the account connected.
  </Step>

  <Step title="Check the account">
    Confirm connection and available capacity before starting work. Use a dedicated provider project key with its own spending limit for automated pipelines. Follow the provider's terms.
  </Step>
</Steps>

For a custom integration, the authorization-session endpoints return the consent instructions and current state. Treat only `connected` with an `account_id` as success. After an uncertain code submission, read session state before submitting again; the code may already have been used. A queued or pending session still needs observation, and some flows need the person's returned code.

## Harnesses and models

Discover models through `GET /api/harnesses/{harness}/models` in the [execution funding reference](/api-reference/tags/execution-funding), and read the current harness policy. Use the returned model IDs, thinking levels and service tiers instead of hardcoding a list. Catalog discovery does not reserve execution capacity. The table summarizes supported funding methods; availability can change and follows the returned policy and model catalog.

| Harness | Personal subscription account | Provider API key | Melso credits |
| - | - | - | - |
| `codex` | Codex | OpenAI | Supported |
| `claude` | Claude Code | Anthropic | Supported |
| `cursor` | Cursor | Unsupported | Unsupported |
| `pi` | Unsupported | Unsupported | Supported |
| `melso` | Unsupported | Unsupported | Supported |

Availability follows the returned policy and model catalog. Cursor requires an enabled, usable connected Cursor account; it has no provider-key or Melso-credit fallback. Pi always uses Melso credits. The `melso` harness uses Melso tools and permitted connected apps; it does not accept a selected worker or thinking level, and starts a computer only when a command requires one. For coding harnesses, choose permitted Cloud execution or a [local runtime](/cli/local-runtimes).

## Harness access and BYOK

Read the current harness policy before changing funding. `PUT /api/provider-accounts/harnesses/{harness}` replaces the policy, so send all required policy fields: omitted booleans become false. The [endpoint schema](/api-reference/tags/execution-funding) defines required fields and limits.

The returned policy separates enablement, supported methods, saved-key health, connected-account capacity and Gateway budget. Inspect `next_method` and `next_reason` to see what the next execution would use or why it cannot start. Saving a policy does not guarantee credits or capacity.

For provider API keys, omission preserves the existing key; a new value replaces it. Keep keys in a secret manager, never Task text, client code or logs.

<Warning>
  Removing a provider API key requires disabling its use in the same policy update. Confirm another permitted funding method before removing or replacing it if Tasks must keep running. Saved key values cannot be read back.
</Warning>

Gateway limits use decimal integer strings in `gateway_limit_ticks`. A zero value resets to the default cap; it does not prohibit spending. Set `gateway_enabled: false` to disable Gateway funding. A cap below settled charges plus reservations returns a conflict. Changing policy does not erase usage already incurred.

Cloud execution also requires company access and usable compute funding under the company's agreement, including when a provider API key funds the model. Read the returned failure reason and current Billing state if work cannot start. A model catalog result or saved funding policy is not a successful Run.

## Account lifecycle

Pausing retains the account's stored credentials. Usage can be stale; requesting a refresh does not establish that quota data is already current. Inspect the account again before relying on it.

<Warning>
  Disabling an account revokes its stored credentials. Re-enabling may require a new consent flow. Use pause when you want to stop new use while retaining the connection.
</Warning>

Connection and capacity errors need different remedies. Reconnect an account that requires authorization; wait when capacity is busy; correct an unsupported funding choice before retrying. See [Errors](/api-reference/errors) and the [execution funding endpoints](/api-reference/tags/execution-funding) for status details.

## MCP clients

Start with [MCP setup](/mcp/connect) at `https://melso.ai/api/mcp`. An authorized client can discover execution availability and request work after funding is configured. It cannot administer provider credentials through MCP.

## Managed execution customers

An `admin` company API key can create non-login execution identities with `POST /api/execution-identities`: `{external_id:string,name:string}`. The external ID is unique within that integration and company; repeating it returns the original ID. `GET /api/execution-identities` lists its identities. `DELETE /api/execution-identities/{identityId}` revokes one; revoked IDs are not reused.

Send `X-Execution-Identity-ID: <identity UUID>` with that key to the existing provider account, OAuth auth-session, import and harness-policy endpoints. Melso verifies the identity belongs to the active key's integration and company. Subscription accounts, provider API keys, quotas and funding fallback belong to this customer rather than the service key. Ordinary company-key identities still cannot connect or borrow subscription accounts. Managed identities cannot sign in or create personal access tokens.

Create an isolated Task with `execution_identity_id` to bind its customer before execution begins. Future input, start, resume and question continuations retain that funding identity, including when another company member responds. The Task creator and retry receipt remain attributed to the API caller. The binding cannot be changed by Task updates. Revoking the identity or parent key blocks new execution and subscription credential renewal.

Managed customers use their own subscription accounts or explicit grants to that exact customer. To grant an account, send `PUT /api/provider-accounts/{accountId}/execution-identities/{identityId}` with the owner's `X-Execution-Identity-ID`; use `DELETE` to revoke the grant. Both customers must belong to the same integration and company. Company-wide subscription shares do not automatically grant managed customers access. Execution uses only funding the customer is authorized to access.

Start an authorized integration with the [API quickstart](/api-reference/quickstart).


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