Skip to main content
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.
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 owns the request and response schemas. The first MCP 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 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

1

Choose your funding

Open Settings → AI providers and choose the provider or funding method available for your harness.
2

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

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

​
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 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.
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.
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.
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.
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 and the execution funding endpoints for status details.

​
MCP clients

Start with MCP setup 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.