# Tetrees MCP 2.3.0 operations guide Tetrees MCP is one authenticated server for discovering, owning, downloading, running, growing, uploading, auditioning, and publishing Tetrees AI Packs. Create a revocable API token in Account and keep it in the MCP process environment as `TETREES_TOKEN`, or send it as `Authorization: Bearer ` to `https://ex.tetrees.ai/mcp`. ## Connect ```json { "mcpServers": { "tetrees-ai": { "command": "npx", "args": ["-y", "https://ex.tetrees.ai/pkg/tetrees-mcp.tgz?v=2.3.0"], "env": { "TETREES_API_URL": "https://ex.tetrees.ai/api", "TETREES_TOKEN": "", "TETREES_CLIENT_EXTENSIONS_FILE": "", "OPENAI_API_KEY": "", "ANTHROPIC_API_KEY": "", "ZAI_API_KEY": "" } } } } ``` Remove unused provider-key entries. A BYOK key is transmitted only for the selected request and is never persisted in a run, log, Pack, or memory record. Remote Streamable HTTP (same account token per request): ```json { "mcpServers": { "tetrees-ai": { "url": "https://ex.tetrees.ai/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Hosted HTTP does not execute local client extensions or local attachment paths. Use stdio on a machine you control for those. Discovery: `https://ex.tetrees.ai/.well-known/mcp.json`. `TETREES_CLIENT_EXTENSIONS_FILE` is optional unless you execute maker-declared client capabilities. It points to a user-owned file; it is never uploaded: ```json { "version": 1, "bindings": [ { "extensionId": "maker.workspace", "kind": "https_api", "baseUrl": "https://api.example.com", "timeoutMs": 20000, "methods": { "save_memo": { "path": "/v1/memos", "httpMethod": "POST", "headers": { "authorization": "env:WORKSPACE_API_TOKEN" } } } }, { "extensionId": "maker.analysis_mcp", "kind": "mcp", "command": "npx", "args": ["-y", "@maker/analysis-mcp"], "envKeys": ["ANALYSIS_API_TOKEN"], "timeoutMs": 20000, "methods": { "analyze": "analyze_dataset" } }, { "extensionId": "maker.local_formatter", "kind": "local_skill", "command": "/absolute/path/skill-runner", "args": [], "envKeys": [], "timeoutMs": 20000, "methods": { "format": "format_memo" } } ] } ``` For HTTPS, header values may only reference environment keys declared by the auditioned Pack. Nested MCP bindings map Pack method ids to actual MCP tool names. A local-skill child receives one JSON line `{ "method": "...", "arguments": {} }` and must return one JSON value. Commands run without a shell and receive only PATH plus explicitly declared environment keys. ## Buyer and agent run 1. `search_ai_packs` 2. `acquire_free_ai_pack`, or purchase a paid Pack on the website 3. `list_owned_ai_packs` 4. `get_ai_pack_report` and `get_ai_pack_runtime_profile` 5. `list_agent_models` 6. `quote_agent_run` 7. `run_ai_pack` 8. optionally `download_ai_pack` The quote reports the maximum reservation, available balance, and `canAfford`. Points pay for hosted model usage. BYOK pays the provider directly, but a selected Tetrees-hosted skill such as `web_search` still reserves its disclosed Points. Attachments are limited to five explicit TXT, Markdown, CSV, TSV, JSON, YAML, XML, PDF, or DOCX paths and are discarded after the request; only filename, size, media type, and digest metadata remain. Runtime, Agent AVCP, and hosted growth share a distributed admission layer with global, per-workload, per-provider, and per-user limits. A request may wait for bounded capacity, but Points are debited only after admission. A full or timed out queue returns `429 AI_WORKLOAD_BUSY` plus `Retry-After`; nothing is charged. Stale admitted work is recovered from its durable record and any debit is returned exactly once. ## Reviewed growth Use `propose_ai_pack_growth`, `accept_ai_pack_growth`, and `list_ai_pack_growth`. Nothing activates at proposal time. Accepted memory is encrypted, owner-scoped, and available only to that owner and Pack. Skill and evaluation proposals stay non-executable audit deltas; a maker must place an executable change in a higher immutable TAIP/1 version and pass Agent AVCP again. Hosted provider normalization has a disclosed Point charge in the growth-state response. OpenAI BYOK normalization and portable normalization cost zero Tetrees Points. Acceptance performs an affordability check before admission. `list_ai_pack_growth` also returns `activeSequence`, selectable `versions`, usage, and limits. Sequence `0` is always the signed base Pack with no hosted owner memory. Use `select_ai_pack_growth_version` with confirmation `SELECT_GROWTH_CHECKPOINT` to make a checkpoint the account default, or pass `growthVersion` to `quote_agent_run` and `run_ai_pack` for an explicit run. Selection is reversible and never modifies the seller Pack. The same saved account-and-Pack default appears in Agent Studio on the product page. This is deliberately separate from the seller's semantic `.taip` version: Pack code, skills, policies, and evaluation changes require a higher immutable Pack version and a fresh Agent AVCP audition, while a checkpoint selects only the owner's accepted hosted memory. A quota rejection leaves both the selected checkpoint and existing memories unchanged. Hosted persistence is capped at 20 memory checkpoints/128 KiB per Pack and 100 checkpoints/1 MiB per account, with 16 KiB per memory. Proposal history is capped at 40/256 KiB per Pack and 200/2 MiB per account. A local MCP host may keep additional local state outside Tetrees storage; Tetrees does not upload or count it. For an explicit comparison, quote and run with the same `growthVersion`; the quote binds that checkpoint into its cost/affordability contract. Omitting the field uses the saved default. This lets a user try the signed base Pack or an earlier checkpoint for one run without silently changing future runs. ## Custom client capabilities TAIP/1 supports client-only `mcp`, `https_api`, and `local_skill` extensions. Every declared method has a strict object input schema, a read/write effect, and a confirmation policy. Every method needs a behavior eval; every write also needs a safety eval and `per_call` confirmation. Publication requires the Agent AVCP `clientExtensionContracts` gate to pass. Call `prepare_local_ai_pack_run` with exact extension ids. Approve write methods only as `extensionId.methodId` for that plan. Then call `execute_client_extension` for one method. A write needs the exact one-call phrase `APPROVE extensionId.methodId`. The local MCP process verifies ownership, the signed profile, binding kind, method, JSON arguments and confirmation before executing. Tetrees hosting never receives the client binding or credential. HTTPS calls require TLS, do not follow redirects, and cap response size. Nested MCP calls discover the mapped tool before invoking it. Local skills run as bounded no-shell children. Secrets echoed by a destination are redacted before the result returns to the model. ## Maker lifecycle 1. `accept_ai_pack_terms` 2. `create_ai_pack_draft` 3. `update_ai_pack_draft` 4. `upload_ai_pack` and `upload_ai_pack_image` 5. `get_ai_pack_submission_readiness` 6. `submit_ai_pack_for_audition` 7. `quote_ai_pack_audition` 8. `run_ai_pack_audition` 9. `get_ai_pack_private_report` 10. `publish_ai_pack` Versions are immutable and must increase semantically. A failed audition remains private, returns its failing gates, and cannot be published. ## MCP-native discovery - Resource: `tetrees://runtime/skills` - Prompt: `run_ai_pack_with_client_tools` ## Errors and safe retries - `401`: invalid or revoked token - `402`: insufficient Points; execution does not start - `403`: ownership, entitlement, or seller-scope failure - `409`: stale quote/version or single-claim conflict - `410`: expired download or retired route - `429`: rate limit, or `AI_WORKLOAD_BUSY` with `Retry-After`; no workload debit occurred Retry safe reads with bounded jitter. After a mutation timeout, inspect the resulting version, run id, growth sequence, or report before retrying.