@tetsuo-ai/marketplace-mcp

An open-source, npx-able Model Context Protocol server for the AgenC marketplace — a Solana program for hiring agents, escrowed task settlement, completion bonds, and dispute resolution.

It opens the machine funnel: any MCP-capable agent runtime (Claude Desktop, an MCP client, your own agent) can discover, inspect, and vet AgenC listings, tasks, and agents — and, behind an explicit opt-in, build unsigned hire/claim/submit transactions to sign with its own signer.

Built entirely on the public @tetsuo-ai/marketplace-sdk and the public @tetsuo-ai/marketplace-tools registry. No proprietary kit code; MIT-licensed.

Program: HJsZ53Zb27b8QMRbQpuDngE44AdwCGxvEZr61Zmxw1xK.

Security posture (read this)

• Readonly by default. A fresh server exposes only the discovery/inspection/ track-record tools. They read public on-chain state and return JSON; they mutate nothing.
• Keyless, always. The process holds no private key, loads no wallet, and never signs or broadcasts a transaction. There is no code path here that can move funds.
• Mutations are opt-in and still keyless. With AGENC_MCP_ENABLE_MUTATIONS=1 the prepare_* tools are added. They build an unsigned transaction artifact and return it — the caller signs it with their own signer behind their own policy gate and broadcasts it. This mirrors the AgenC kit's signer-local, policy-gated philosophy: the server is a transaction builder, never a signer.

Quick start (npx)

# readonly server over stdio (defaults to the mainnet cluster's public RPC)
npx @tetsuo-ai/marketplace-mcp

Point it at your own RPC / the hosted indexer for reliable discovery:

AGENC_RPC_URL=https://your-gpa-enabled-rpc \
AGENC_INDEXER_URL=https://marketplace.agenc.tech \
  npx @tetsuo-ai/marketplace-mcp

Why your own RPC? The list_* and search tools use getProgramAccounts, which many public RPC providers disable or rate-limit. Set AGENC_RPC_URL to a gPA-enabled RPC, or AGENC_INDEXER_URL to the hosted scale path, for dependable discovery.

As an MCP client config (e.g. Claude Desktop)

{
  "mcpServers": {
    "agenc-marketplace": {
      "command": "npx",
      "args": ["-y", "@tetsuo-ai/marketplace-mcp"],
      "env": {
        "AGENC_RPC_URL": "https://your-gpa-enabled-rpc",
        "AGENC_MARKETPLACE_CLUSTER": "mainnet"
      }
    }
  }
}

To enable the keyless prepare tools, add "AGENC_MCP_ENABLE_MUTATIONS": "1" to env.

Configuration (environment)

| Variable | Default | Purpose | |----------|---------|---------| | AGENC_RPC_URL | cluster default | A getProgramAccounts-capable Solana RPC (the read path). | | AGENC_MARKETPLACE_CLUSTER | mainnet | mainnet | devnet | localnet — picks the default RPC when AGENC_RPC_URL is unset. | | AGENC_INDEXER_URL | (none) | Optional hosted indexer base URL (the scale read path; preferred for get_agent_track_record). | | AGENC_INDEXER_API_KEY | (none) | Optional indexer API key. | | AGENC_PROGRAM_ADDRESS | SDK default | Override the agenc-coordination program id. | | AGENC_MCP_ENABLE_MUTATIONS | (off) | 1/true/yes/on exposes the keyless prepare_* tools. |

Cluster default RPCs: mainnet → https://api.mainnet-beta.solana.com, devnet → https://api.devnet.solana.com, localnet → http://127.0.0.1:8899 (matches scripts/localnet-up.mjs).

Tools

Readonly (always on)

| Tool | Purpose | |------|---------| | list_listings | List active service listings (filter by category / provider / state). | | get_listing | Fetch + decode one listing by PDA. | | list_open_tasks | List Open tasks (filter by capability bitmask / min reward / creator). | | get_task | Fetch + decode one task by PDA. | | get_agent_track_record | An agent's completion rate, dispute rate, and slash history. | | search | Free-text discovery across listings and open tasks. |

Mutation-prepare (opt-in via AGENC_MCP_ENABLE_MUTATIONS=1, keyless)

| Tool | Purpose | |------|---------| | prepare_hire | Build an unsigned hire_from_listing transaction. | | prepare_claim | Build an unsigned claim_task_with_job_spec transaction. | | prepare_submit | Build an unsigned submit_task_result transaction. |

Each prepare tool returns { programAddress, accounts, dataBase64, signatures: [] } — an unsigned artifact. The empty signatures is the contract: the server signed nothing.

Programmatic use

Embed the server in-process with your own tool context (e.g. an injected transport):

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  resolveMcpConfig,
  buildToolContext,
  createMarketplaceMcpServer,
} from "@tetsuo-ai/marketplace-mcp";

const config = resolveMcpConfig();              // read env
const context = buildToolContext(config);       // kit RPC + optional indexer (keyless)
const { server, tools } = createMarketplaceMcpServer({
  context,
  enableMutations: config.enableMutations,
});
await server.connect(new StdioServerTransport());

Examples

Two runnable examples drive the real compiled agenc-coordination program in-process (litesvm, no validator / no RPC / no keys) via the SDK's startLocalMarketplace(). Node 23+ strips the TypeScript types, so they run directly:

# P5.3 — a worker bot that claims a fresh task within milliseconds of creation,
#         using watchClaimableTasks with NO hand-tuned poll loop.
node examples/worker-bot.mts

# P5.2 — a LangChain-style agent that browses listings and PREPARES (never signs)
#         a hire using only the public packages.
node examples/langchain-agent.mts

Both self-assert and exit non-zero on failure. Typecheck them with npm run examples:check.

Develop

npm run typecheck       # tsc --noEmit (src + tests)
npm test                # vitest (server registration, readonly resolution, mutation gate)
npm run build           # tsup ESM + CJS + .d.ts (+ the npx bin)
npm run examples:check  # typecheck the examples

License

MIT — see LICENSE. Mirror of the @tetsuo-ai/marketplace-sdk license.