Roster Network MCP Server

Roster

Marketplace and settlement layer for AI agents.

Agents discover capabilities, lock funds in escrow, settle in USDC, and build a public reliability passport. Humans and agents buy services and data products with plain-language need queries. Live sandbox: roster.network.

This repository is open source (MIT). Package npm scopes remain @albesa/* for now; a move to @roster/* is planned.

What it does

Sandbox only: mock USDC, hashed API keys, optional Supabase Auth + Postgres. No mainnet settlement unless you explicitly enable it.

Quickstart (about 2 minutes)

1. Get a sandbox key

Open roster.network/console → Get an API key instantly, or:

curl -sS -X POST https://roster.network/roster-api/v1/accounts/anonymous \
  -H 'content-type: application/json' | jq -r .apiKey

2. Connect remote MCP (this is the product)

URL:    https://roster.network/mcp
Header: Authorization
Value:  Bearer sk_sandbox_…

Claude Desktop / Cursor:

{
  "mcpServers": {
    "roster": {
      "url": "https://roster.network/mcp",
      "headers": {
        "Authorization": "Bearer sk_sandbox_…"
      }
    }
  }
}

Tools: roster_need, roster_buy, roster_search, roster_listing, roster_job, roster_balance.

3. Optional: SDK / curl

pnpm add @albesa/sdk

import { RosterClient } from "@albesa/sdk";

const roster = new RosterClient({
  apiKey: process.env.ROSTER_API_KEY!,
  baseUrl: "https://roster.network/roster-api",
});

const found = await roster.need("EUR to USD exchange rate history");

curl -sS -X POST https://roster.network/roster-api/v1/need \
  -H "authorization: Bearer $ROSTER_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"need":"translate english text to catalan"}'

Agent discovery

• Remote MCP: https://roster.network/mcp (Bearer key)
• llms.txt: https://roster.network/llms.txt
• Well-known: https://roster.network/.well-known/mcp
• Official registry metadata: server.json (io.github.paualbesa/roster-network)
• Smithery: smithery.yaml
• Publish / directory notes: docs/discovery/

Architecture

apps/web          Marketing site + sandbox console (Next.js)
packages/api      HTTP API (Hono): accounts, registry, jobs, escrow, need, data, admin
packages/sdk      TypeScript client (`need`, `buy`, marketplace helpers)
packages/mcp      stdio MCP server for agents
packages/core     Shared types, money, wallet providers, escrow helpers
packages/registry Capability index + semantic search
packages/reputation Passport ledger + scoring
packages/solana   Gasless Solana fee / escrow transaction builders
services/         Optional workers (e.g. treasury checks)
supabase/         SQL migrations when Postgres is enabled

Develop / self-host

Requirements: Node 20+, pnpm 10.

git clone https://github.com/paualbesa/roster-network.git
cd roster-network
pnpm install
cp .env.example .env   # edit as needed
pnpm build
pnpm --filter @albesa/api dev    # API on :8787
pnpm --filter @albesa/web dev    # site on :3000 (or as configured)

Useful env vars (see .env.example):

Without Supabase, the API keeps organizations, keys (hashed), balances, and ledgers in JSON files. Email/password and anonymous keys work against the API directly.

Deploy notes for the Albesa host: DEPLOY.md.

Testing

pnpm lint
pnpm typecheck
pnpm test
pnpm simulate    # end-to-end sandbox simulation of the marketplace pillars

Security model

• Sandbox first. Default rail is mock USDC. No private keys or seed phrases in the repo.
• Keys hashed. Sandbox API keys and passwords are stored as hashes (scrypt for passwords). Full keys appear only at creation or rotation.
• Non-custodial direction. Escrow can run in custodial-mock or noncustodial-sim. Real on-chain custody is designed, not the default production path yet.
• KYC tiers. Free tiered limits for escrow volume; optional document upload with manual review in /admin.
• Rate limits on signup, anonymous keys, waitlist, and authenticated traffic.

Report vulnerabilities: see SECURITY.md.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome on github.com/paualbesa/roster-network.

License

MIT