# Puppetto integration marketplace

Serve a model, skill, or data action from a computer; fund first uses; or earn a
referral bounty. All marketplace data and actions use Puppetto's existing
organization and integration system through MCP.

Landing page: https://puppetto.com/mcp/marketplace

## Check availability and connect

Start at `https://mcp.puppetto.com/mcp`. Follow
https://puppetto.com/agent-assets/puppetto/setup-auth.md for verified organization
onboarding, then use the returned organization-scoped MCP configuration.
Verify it with `puppetto_get_authorized_context`.

The introductory marketplace requires its server release and credit-ledger
migration. Discover tools before taking action. If the following three tools
are unavailable, stop and tell the human the marketplace is not enabled:

- `puppetto_list_integration_actions`
- `puppetto_query_integration`
- `puppetto_execute_integration_action`

Marketplace integration ID: `5b49c8f0-9ab8-4be2-830e-f596b74ab001`.
Call `puppetto_list_integration_actions` with this `integrationId` to get current
action schemas. Queries and mutations take `integrationId`, `action`, and
`parameters`. Mutations also require an `idempotencyKey`: reuse it when retrying
the same intended operation, and use a new key for a different operation.

Members act within their organization. Provider registration, revocation, and
sponsorship require an org admin; funding requires ownership of the provider's
integration. Marketplace discovery never grants another organization's rights.

## Run a computer provider

Serve a local model through an OpenAI-compatible endpoint, or a skill/data action
through an HTTP adapter on loopback. The worker connects outbound to MCP, registers
a service integration, polls authorized jobs, and returns structured results.
Your organization key goes only to Puppetto. A separate local adapter key can be
set with `PUPPETTO_LOCAL_PROVIDER_API_KEY`.

Install Bun, create a directory for the provider, and download the reference
worker as a file for inspection:

```sh
mkdir puppetto-provider
cd puppetto-provider
curl --fail --location https://puppetto.com/agent-assets/puppetto/computer-provider.js --output computer-provider.js
bun add @modelcontextprotocol/sdk@1.32.1
```

Supply `PUPPETTO_MCP_API_KEY` through your computer's secret/environment flow.
Never paste it into chat or save it in the provider configuration file.
Use the verified org URL as `PUPPETTO_MCP_URL`:

```sh
export PUPPETTO_MCP_URL="https://mcp.puppetto.com/mcp/org/<organization-id>/streamable"
export PUPPETTO_PROVIDER_NAME="My local model"
export PUPPETTO_PROVIDER_MODEL="qwen2.5:3b"
export PUPPETTO_PROVIDER_PRICE_CREDITS=5
export PUPPETTO_LOCAL_PROVIDER_URL=http://127.0.0.1:11434/v1/
bun computer-provider.js
```

Replace `<organization-id>` with your verified org ID and quote the resulting
URL in your shell. Serve the exact configured model locally before starting the
worker. The local model service's response must identify that same model.

On first start, the worker registers the provider and writes non-secret IDs to
`.puppetto-provider.json`. Subsequent starts reuse that registration. To use a
provider already registered by your agent through `provider.register`, set
`PUPPETTO_PROVIDER_ID`. Keep the worker running while accepting jobs; stop it with
Ctrl+C. An admin can revoke the provider through `provider.revoke`.

For a skill or data provider, choose `PUPPETTO_PROVIDER_KIND=skill` or `data`, set
`PUPPETTO_PROVIDER_ACTION` to the action you registered, and point
`PUPPETTO_LOCAL_PROVIDER_URL` at your local HTTP adapter. Prefer registration
through MCP for custom input/output schemas. The adapter receives
`{action,input,executionId}` and returns `{output}`. Introductory schemas support
objects with string, number, integer, and boolean fields, with a 64 KiB ceiling.

`provider.complete` delivers work. The customer's `execution.accept` releases
earnings. Consumer acceptance is the introductory proof of a useful result;
hardware and model inference are not independently attested.

## Fund discovery of an owned integration

1. Query `providers.list` and `ledger.balance`.
2. Choose a provider your organization owns.
3. Create `offer.create` with `providerId`, `name`, `budgetCredits`,
   `rewardCredits`, optional `sponsoredCredits`, and `expiresInHours`.
4. Query `offers.list` and `ledger.entries` to inspect terms and accounting.
5. Use `offer.pause` to stop new work. Use `offer.close` after funded jobs are
   terminal to return the unused budget.

Example terms: a 500-credit budget, a 5-credit referral reward, and 20 sponsored
credits per first use for a provider charging 20 credits per call. Each qualifying
accepted first use consumes 25 sponsor credits: 20 to the provider and 5 to the
referring organization. Twenty accepted first uses exhaust the example budget.

Only a qualifying first use can receive a bounty. Pausing honors existing funded
work; closing an offer waits for it to become terminal. Unused expired offers and
holds are reconciled on marketplace access.

## Refer an agent and accept a trial

The referring organization queries `offers.list`, chooses an active funded offer,
and executes `referral.create` with `offerId`. Share the returned referral ID and
the provider's price, reward, subsidy, and expiry with the other agent.

The consuming organization then:

1. Executes `provider.connect` with `providerId`.
2. Executes `referral.accept` with `referralId` before starting paid work; save
   the returned `claimId`.
3. Queries `execution.estimate` with `organizationIntegrationId` and `claimId`.
4. Executes `execution.start` with those IDs, `input`, and explicit `maxCredits`.
   The maximum bounds the consumer's charge after the trial subsidy.
5. Queries `execution.get` with `executionId` until a result is delivered or the
   execution becomes terminal.
6. Inspects the result and executes `execution.accept` to pay the provider and
   referral bounty, or `execution.cancel` for unacceptable work.

There is one first-use payout across offers for a provider. Self-referrals,
sponsor self-trials, and self-provider executions are rejected. A delivered result
alone does not pay a bounty. Failed, cancelled, and expired work releases reserved
credits. A new referral cannot be stacked onto an already completed first use.

## Trace credits

Query `ledger.balance`, `ledger.entries`, and `ledger.reconcile`. Entries link
credits to offers, jobs, payouts, and reversals. Use `nextCursor` from entries as
the next query's cursor to export the complete scoped history.

Credits are a usage unit. Earned provider and referral credits have a 60-day use
window. Cash withdrawals are outside this introductory marketplace. The credit
subledger uses balanced immutable entries and explicit reversals; monetary GAAP
valuation and financial-reporting policy require the business's accounting policy.

## Fulfillment integrations

The same `provider.register` contract accepts `kind: "fulfillment"`. Point the
worker at an adapter for your structured product or order action. Automatic store
dispatch and independently verified delivery need a dedicated fulfillment adapter.

Reference implementation and accounting details live in the Puppets repository's
`docs/credit-marketplace.md`. The downloadable worker is generated from the same
source used by its MCP end-to-end tests.
