Connect AI Clients to Tetrees Agent with MCP and the Public API

What Is Tetrees Agent EX?

Tetrees Agent EX is a public integration kit for working with Tetrees AI Packs through the hosted Tetrees Agent MCP server and API. It provides clients, configuration examples, and safe extension samples for buyers, builders, and sellers.

The kit exposes the developer-facing contract rather than the internals of the hosted service. It does not include Tetrees Agent implementation details, private Pack intelligence, Agent AVCP scoring rules, service prompts, moderation systems, storage infrastructure, or production credentials.

Tetrees-hosted operations do not require a local GPU. Model-funded runs are quoted in Tetrees Points before execution. After acquiring a Pack, users can also supply a supported provider key to their local MCP process.

What You Can Build

Buyer and Operator Workflows

Buyers and operators can use the public contract to:

• Search the AI Pack catalogue.
• Inspect a Pack's public Agent AVCP report and runtime profile.
• Quote a run before spending Tetrees Points.
• Try a Pack through a stateless Point-funded preview.
• Acquire a free Pack or purchase a paid Pack on Tetrees EX.
• Download an owned immutable .taip release.

Builder Workflows

Builders can connect an auditioned Pack to user-controlled capabilities while keeping bindings and credentials on the user's machine. Supported patterns include a fixed HTTPS API, a nested MCP server, and a no-shell local skill.

Seller Workflows

Sellers can create listings, upload immutable Pack versions and images, inspect readiness, run Agent AVCP, review private repair feedback, and publish a release that passes evaluation.

Prerequisites

Before configuring the hosted MCP integration, prepare the following:

• Node.js 20 or newer.
• A revocable API token from the Tetrees Account page.
• An MCP-compatible client if you plan to use the hosted MCP server.
• A local checkout of the repository if you want to run the inspector, CLI, examples, or verification commands.

Keep credentials out of Packs, prompts, source files, and shared MCP configurations. Optional provider keys should exist only in the environment of the local MCP process.

Configure the Hosted MCP Server

Add the following server definition to your MCP client's configuration. Replace the placeholder with your revocable Tetrees account token.

{
  "mcpServers": {
    "tetrees-ai": {
      "command": "npx",
      "args": ["-y", "https://ex.tetrees.ai/pkg/tetrees-mcp.tgz?v=2.2.0"],
      "env": {
        "TETREES_API_URL": "https://ex.tetrees.ai/api",
        "TETREES_TOKEN": "<revocable-account-token>"
      }
    }
  }
}

Restart the MCP client after saving the configuration. The v=2.2.0 suffix prevents npx from reusing an older tarball cached under the same URL. Change this value only when Tetrees publishes a newer MCP contract.

Try a Safe MCP Request

Ask your MCP client to search and quote a Pack without starting a paid run:

Search Tetrees AI Packs for repository issue triage. Show the public Agent AVCP
report and runtime profile for the best match, then quote an 8k/2k Point-funded
run. Do not run it until I approve the quoted maximum.

This request follows the intended safety pattern: discover a Pack, inspect its public evaluation and runtime requirements, request a quote, and wait for explicit approval before spending Points.

Inspect the Public MCP Contract

From the repository directory, install dependencies, export your token, and run the MCP inspector:

npm install
export TETREES_TOKEN="txk_..."
npm run mcp:inspect

The inspector launches the official hosted MCP package and lists its public tools and resources. It also checks the expected buyer, builder, and seller surfaces. Inspection exits without spending Points or changing account state.

Use the Public API CLI

The project deliberately does not load secret files automatically. Copy the relevant values from .env.example into your shell environment rather than expecting the CLI to read them.

export TETREES_TOKEN="txk_..."

Run Read-Only Commands

Start with commands that inspect the service and your account without initiating model work:

npm run tetrees -- status
npm run tetrees -- catalog "research"
npm run tetrees -- models
npm run tetrees -- skills
npm run tetrees -- owned
npm run tetrees -- runtime <pack-id>
npm run tetrees -- report <pack-id>

Use catalog to find a Pack, runtime to review its runtime profile, and report to inspect its public Agent AVCP report. The models and skills commands expose the supported public choices, while owned lists Packs associated with the account.

Quote Before Running

A quote does not start a model request. Supply the selected Pack and model identifiers:

npm run tetrees -- quote <pack-id> <model-id>

Review the exact model, token ceiling, hosted skills, growth checkpoint, and quoted Point commitment before approving execution.

Confirm a Point-Spending Run

To start a run, include the exact confirmation flag:

npm run tetrees -- run <pack-id> <model-id> "Your task" --confirm-spend

Point-funded previews are stateless, and unused reserved Points are returned. The CLI redacts secret-shaped response fields and reports Tetrees error codes, HTTP status values, and Retry-After information. It does not automatically retry a mutation.

Follow the Buyer Flow

A cautious buyer workflow proceeds in the following order:

1. Search for a Pack that matches the task.
2. Inspect its public Agent AVCP report and runtime profile.
3. Quote the exact model, token ceiling, hosted skills, and growth checkpoint.
4. Approve and run a Point-funded stateless preview.
5. Acquire a free Pack or buy a paid Pack through Tetrees EX.
6. Use ownership benefits such as download, BYOK, saved growth, and client extensions.

The repository includes a documented read-only discovery and quote example:

node examples/buyer/discover-and-quote.mjs "incident response"

Replace incident response with another search phrase to explore Packs for a different use case.

Add Local Capabilities as a Builder

A published Pack can declare client extensions that have passed Agent AVCP. The extension's actual binding and credentials remain local, so Tetrees hosting does not inherit those permissions.

Choose a Binding Pattern

• https_api: Connect to a fixed HTTPS base URL with declared methods and environment-backed headers.
• mcp: Start a nested MCP server without a shell and map it to declared tool names.
• local_skill: Start a no-shell child process that accepts one JSON request and returns one JSON result.

Use examples/extensions/client-extensions.example.json as the configuration starting point. The repository also provides examples/extensions/local-skill/issue-summary.mjs as a local-skill example and docs/BUILDER_GUIDE.md for the complete builder contract.

A write method requires the exact per-call approval phrase APPROVE extensionId.methodId. Do not treat general conversational approval as permission to perform a write.

Publish a Pack as a Seller

The seller path is contract-driven. First inspect readiness and reports without changing the Pack:

node examples/seller/check-readiness.mjs <pack-id>

When a new release is ready, upload one higher immutable version with explicit confirmation:

node examples/seller/upload-pack.mjs <pack-id> 1.1.0 ./release.taip --confirm-upload

After upload, use the hosted MCP tools or the Tetrees API reference to complete the publishing workflow:

1. Submit the uploaded version.
2. Request an Agent AVCP quote.
3. Confirm the exact Point amount before running Agent AVCP.
4. Inspect the private report and repair feedback.
5. Publish only the digest that passed evaluation.

Refer to docs/SELLER_GUIDE.md and examples/seller/pack-listing.example.json when preparing a listing.

Advanced Safety and Reliability Tips

Separate Secrets from Shared Configuration

Store the Tetrees token and optional provider keys in local process environments. Never embed provider credentials in a Pack, prompt, source file, or configuration that may be shared. Use revocable tokens so access can be withdrawn when needed.

Do Not Automatically Retry Mutations

For failed write operations, inspect the reported Tetrees error code, HTTP status, and Retry-After value before deciding what to do. Automatic retries can repeat uploads, purchases, runs, or other state-changing operations.

Pin the Hosted MCP Contract Deliberately

Retain the documented query suffix on the MCP package URL to avoid stale npx cache entries. Update it only in response to an officially published contract version.

Review the Public Boundary

Before contributing, read SECURITY.md and docs/PUBLIC_BOUNDARY.md. Contributions should interact only with the documented public authenticated contract and must not assume access to Agent internals, private Pack data, scoring fixtures, signing keys, databases, admin APIs, or deployment infrastructure.

Verify the Repository

Run the supplied checks before distributing changes or preparing a package:

npm test
npm run check:public-boundary
npm pack --dry-run

Useful Public References

• Tetrees MCP guide
• Tetrees API documentation
• OpenAPI 3.1 specification
• Postman collection
• AI Pack catalogue

Conclusion

Tetrees Agent EX provides a transparent public contract for discovering, evaluating, running, extending, and publishing Tetrees AI Packs. Begin with read-only inspection, request an exact quote before model-funded work, require explicit confirmation for spending and writes, and keep all user-owned credentials and extension permissions local.