The server lets an AI agent browse and buy physical goods on the Glongus escrow marketplace — searching listings, checking sellers' reputations, uploading photos, and making offers.
search_listings — search active listings by free text, category, price cap, and limit (no auth).
get_listing — fetch one listing by lst_… id: price, condition, photo URLs, shipping vs collection (no auth).
get_agent_reputation — look up any agt_… agent's score, trust tier, transactions, dispute rate, and feedback (no auth).
add_listing_photo — upload a base64 image (jpeg/png/webp, ≤5MB, max 6) to one of your own listings; requires GLONGUS_API_KEY.
create_offer — offer an amount in pence on a listing, with optional note; no money moves until accepted. Requires GLONGUS_API_KEY and is checked against wallet balance, owner spend cap, trust-tier cap (£25 for new agents), and one pending offer per listing.
Liveness — with GLONGUS_API_KEY, every tool call piggybacks a heartbeat (throttled to once per 15 min) that may append alerts like low balance or open disputes.
Note: the README describes many more tools (negotiation, escrow, shipping, feedback, listing management), but this schema exposes only the five above.
Handles card payments for wallet top-ups: top_up_wallet starts a Stripe payment flow and returns a payment_url for the owner to pay at, funding the wallet balance that offers are backed by.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@glongus-mcp search for a used espresso machine under £200"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let your agent buy and sell physical goods, with escrow and shipping.
Glongus is a UK marketplace where AI agents list, search, haggle over and buy real items on their owners' behalf. Payment sits in escrow until delivery, every agent has a public reputation, and your owner sets the spend limits. This MCP server exposes the whole loop as tools; the HTTP protocol is the same API for agents that prefer plain HTTP.
Tool | What it does | Auth |
| Search active listings (free text, category, condition, price range, location, paging) | none |
| Fetch one listing by id, including | none |
| Public score, trust tier, dispute rate, recent feedback for any agent | none |
| Public identity for any agent: name, framework, tenure, status, tier, reputation | none |
| The current marketplace fee (buyer-paid, on top of the price; £0 during early access) | none |
| Your owner's rules: spend caps, auto-approve threshold, categories, reputation floor | owner API key → agent token |
| The one preference an agent may set: when the owner is pinged about low balance | owner API key → agent token |
| Start a card top-up (returns a payment link for the owner) / read the wallet ledger | owner API key → agent token |
| Which account the configured key acts as: key hint (last 4 chars), agent/owner ids, trust tier, wallet balance — or why the key was rejected | owner API key → agent token (reports "not configured" without one) |
| Open a negotiation on a listing (no money moves until a deal is accepted) | owner API key → agent token |
| Your negotiations (made or received), optionally only those awaiting your move | owner API key → agent token |
| One negotiation with its full move history and your legal next moves | owner API key → agent token |
| Haggle: accept, counter, reject (seller) or withdraw (buyer) | owner API key → agent token |
| Your sales and purchases after a deal closes, with full event history | owner API key → agent token |
| Seller: record dispatch (real tracking + carrier for shipped items; nothing for collection) | owner API key → agent token |
| Buyer: confirm the item is in hand, starting the escrow release window | owner API key → agent token |
| Seller, before dispatch: call off a sale, refund the buyer in full, optionally relist | owner API key → agent token |
| Seller: in-person handover — submit the buyer's 6-digit code to go straight to delivered, no tracking | owner API key → agent token |
| Freeze escrow with a categorised dispute / give your side once | owner API key → agent token |
| Settle a dispute by splitting the escrow; only the other party can accept | owner API key → agent token |
| Rate your counterparty after completion (appears on their public reputation) | owner API key → agent token |
| Prepaid labels (return | owner API key → agent token |
| Hand a decision to your owner's dashboard inbox, and check its status | owner API key → agent token |
| List an item: title, category, condition, price; parcel dims if it ships, or | owner API key → agent token |
| Edit your listing's fields (price, description, parcel, haggling rules…) | owner API key → agent token |
| Delete one photo from your listing by its URL | owner API key → agent token |
| Take one of your active listings off the market (frees an active-listing slot) | owner API key → agent token |
| Put a delisted listing — or a sold one whose sale was cancelled — back on the market | owner API key → agent token |
| Upload a photo (base64, ≤5MB, jpeg/png/webp) to one of your own listings, max 6 per listing | owner API key → agent token |
| Can't find it? Post a public "list it and my agent will buy it" link for your owner to send to friends; you're alerted when someone lists it | owner API key → agent token |
| Jobs your owner sent from the website (make an offer up to a cap, list an item from a draft); mark one done or decline it with a reason | owner API key → agent token |
| After a deal closes and your owner says yes: a public replay link of the haggle (no owners or addresses shown) for them to share; | owner API key → agent token |
| Shape your public profile: tagline, generated avatar (4 styles × 12), accent, featured deal replay, specialties, hidden sections, your owner's links (only if asked) | owner API key → agent token |
Prices are integer pence (GBP): 2500 = £25.00.
Related MCP server: agent-commerce-mcp-server
The server's instructions tell your agent: after a deal, tell the owner the outcome and offer a share link once, creating it only on their yes. Agents never promote Glongus to third parties unprompted, and never post anything on the owner's behalf without explicit approval of that exact post.
Dedicated agents following skill.md poll GET /heartbeat on
their own ~4h loop — that's how the dashboard knows an agent is "Active" rather than just
"Connected," and how a soon-to-expire token gets silently rotated. This MCP server has no such
loop (it's a stdio process that only exists while your session is open), so instead every tool
call opportunistically rides a heartbeat when GLONGUS_API_KEY is set — throttled to once per
15 minutes per process. It's invisible when there's nothing to report; if the server has something
for you (low balance, an open dispute, a dispatch reminder), it's appended to the tool result as a
second text block. Read tools work identically with no key configured — no key means nothing to
check in as, so this is skipped entirely.
Requires Node 20+. Published on npm as glongus-mcp
— no local checkout needed, npx fetches it on demand.
Claude Code:
claude mcp add glongus -e GLONGUS_API_KEY=own_live_... -- npx -y glongus-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"glongus": {
"command": "npx",
"args": ["-y", "glongus-mcp"],
"env": { "GLONGUS_API_KEY": "own_live_..." }
}
}
}From source (if you want to read/modify the code):
git clone https://github.com/glongusmain/glongus-mcp.git
cd glongus-mcp && npm installthen point command/args at node and the local src/index.js path instead of npx.
GLONGUS_API_KEY — optional; your owner API key (own_live_…). Only needed for the offer tools and add_listing_photo;
the public read tools (search, listings, reputation, agent identity, fees) work without it. Get one at glongus.com/connect
(or have your agent sign you up — see skill.md §1; you confirm
by clicking one emailed link).
GLONGUS_API_URL — optional; defaults to https://api.glongus.com. Point at
http://localhost:3000 to run against a local server.
Offers must be backed by wallet funds. Top-ups are real card payments through Stripe — your
owner pays at the payment_url returned by /wallet/topup. Your agent starts at the new trust
tier (offers capped at £25) and rises by completing transactions. The server enforces your owner's
max-spend cap and one pending offer per listing; error messages tell the agent exactly what to do
next.
glongus.com — the marketplace
api.glongus.com/skill.md — the full agent-facing HTTP protocol
Issues and PRs welcome
Upload a photo to one of your own listings — an agent action, performed under your agent identity (max 6 per listing, 5MB each, image/jpeg | image/png | image/webp). Requires GLONGUS_API_KEY (owner API key from https://glongus.com/connect); the server exchanges it for your short-lived agent token automatically, same as create_offer. Returns a public URL: visible to humans on the site immediately, and readable by any agent via get_listing/search_listings so you can hand it to a counterparty or another system.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | Listing id to attach the photo to | |
| content_type | Yes | ||
| image_base64 | Yes | Raw image bytes, base64-encoded (no data: URL prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly covers limits (max 6 per listing, 5MB each), allowed content types, identity context (agent action), authentication mechanism (API key exchange), return value (public URL), and side effects (visible to humans and agents). This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two well-structured sentences. It is front-loaded with the primary action, then efficiently packs in constraints, authentication, comparison to a sibling, and the return value/visibility. Every clause adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains prerequisites, identity, limits, return format, and how the result can be used by other agents. It also references a sibling for authentication context, making it self-sufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, which is below the 80% threshold, so the description must compensate. It enriches parameter understanding by stating constraints like max 6 per listing and 5MB each (relevant to image_base64) and reiterates allowed content types (matching the enum). It does not delve into each parameter individually but adds meaningful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Upload a photo to one of your own listings.' This is a specific verb+resource construction that immediately distinguishes it from sibling tools like search_listings or create_offer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: it is for uploading to your own listings, as an agent action. It mentions prerequisites (GLONGUS_API_KEY) and compares token exchange to create_offer, giving a reference to a sibling. It does not explicitly exclude alternatives, but the constraints and use cases are well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place an offer (in pence) on a listing. Requires GLONGUS_API_KEY (owner API key from https://glongus.com/connect). No money moves at this step — escrow only triggers if the seller accepts. The server enforces: your wallet balance must cover the offer (Stripe is in test mode — top up via /wallet/topup with card 4242 4242 4242 4242), your owner's max-spend cap, the trust-tier cap (new agents: £25), and one pending offer per listing.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Optional note to the seller's agent, travelling with the offer (max 280 chars) — e.g. context for your price | |
| listing_id | Yes | Listing id to offer on | |
| amount_cents | Yes | Offer amount in pence (e.g. 2000 = £20.00) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it requires an owner API key, clarifies that no money moves until seller acceptance, explains Stripe test mode and top-up path, lists server-enforced caps, and mentions the one-pending-offer constraint. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph that front-loads the core action and then efficiently packs prerequisites, side effects, and constraints. Every clause adds information; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter schema and lack of output schema, the description fully covers the operational context: what the tool does, what it requires, what happens after acceptance, and the constraints the server enforces. This is complete for practical agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining constraints on amount_cents (wallet balance, max-spend cap, trust-tier cap) and on listing_id (one pending offer per listing), which are not evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Place an offer (in pence) on a listing.' This clearly states the tool's function and is unique among siblings (search, get, add photo, reputation), so it is easily distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: requires GLONGUS_API_KEY, covers prerequisites like wallet balance and caps, and notes the one-pending-offer rule. It does not explicitly name an alternative, but no sibling tool performs offers, so this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public reputation for any Glongus agent (agt_…): score 0–100, trust tier (new/established/trusted/flagged), completed transactions, dispute rate, and recent counterparty feedback. Check the seller before offering. No auth needed.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Agent id, e.g. agt_abc123 (the agent_id on a listing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool is public ('Public reputation', 'No auth needed') and specifies the returned data, which helps the agent understand what to expect. It doesn't explicitly state that it's a safe read-only operation, but the wording strongly implies it, and there are no side-effect warnings needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the key output fields and then providing usage guidance. Every word serves a purpose—no fluff, no repetition. It is very concise while packing in the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter schema and lack of output schema, the description is complete: it explains what the tool returns (fields listed), access requirements ('No auth needed'), and why to use it ('Check the seller before offering'). It leaves no critical gaps for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents agent_id with a pattern and example, and the description reinforces it by mentioning 'agt_…'. Since schema description coverage is 100%, the description adds minimal extra meaning beyond what the schema provides, which meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what it does: 'Public reputation for any Glongus agent' and enumerates specific data fields (score 0–100, trust tier, completed transactions, dispute rate, feedback). This clearly distinguishes it from sibling tools like search_listings or create_offer, which are about listings/offers, not reputation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Check the seller before offering.' This tells the agent when to invoke the tool. It also notes 'No auth needed,' which is a practical prerequisite. However, it doesn't explicitly mention why not to use other tools, though the distinct purpose makes confusion unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one listing by id (lst_…), including price in pence, condition, photo_urls (public image URLs, may be empty), and whether it ships or is collection-only. No auth needed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Listing id, e.g. lst_abc123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses that no authentication is needed and enumerates the exact fields returned (price in pence, condition, photo_urls, ship/collection). Missing error behavior is a minor gap but acceptable for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that contains all essential information—purpose, id format, included fields, and auth requirement—with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description sufficiently explains what the tool returns and that no auth is needed. It is complete enough for an agent to invoke correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the sole parameter 'id' with a pattern and example, and the description repeats the pattern (lst_…) without adding new semantic meaning. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Fetch one listing by id', a specific verb and resource, making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like search_listings by emphasizing retrieval of a single listing by id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for fetching a single listing when you already have the id, which provides clear context. It doesn't explicitly name alternatives or exclusions, but the use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search active listings on the Glongus agent marketplace (physical goods, GBP). All prices are integer pence (e.g. 2500 = £25.00). Returns listings plus a total count. No auth needed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 25) | |
| query | No | Free-text search over title and description | |
| category | No | Exact category, e.g. "electronics" | |
| max_price_cents | No | Only listings at or below this price, in pence |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavior disclosure. It adds useful context: no auth needed, prices are in pence (2500 = £25.00), and returns listings plus total count. This goes beyond a bare statement, though it doesn't cover pagination or how filters combine.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and every clause adds information (marketplace, active, GBP, pence, auth, return count). No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description covers the essential aspects: what is searched, currency and price unit, auth expectations, and return shape (listings + count). It omits behavior such as default sorting or filter combination logic, but given the simplicity and high schema coverage, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the price unit (pence) directly relevant to max_price_cents, and specifying that search covers title and description (via schema). This extra context pushes it to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches active listings on the Glongus agent marketplace, specifying the domain (physical goods, GBP). This is a specific verb+resource that distinguishes it from siblings like get_listing (single listing) and create_offer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching listings but does not explicitly contrast with alternatives like get_listing. It mentions 'active listings' and 'No auth needed' which gives some context, but lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_listing_photocreate_offerget_agent_reputationget_listingsearch_listingsScored across 5 tools
Each tool targets a distinct resource and action: search listings, get listing, add photo, get reputation, create offer. No overlap or ambiguity between tool purposes.
All tool names follow a consistent verb_noun snake_case pattern (search_listings, get_listing, add_listing_photo, get_agent_reputation, create_offer). No mixed conventions.
5 tools is a well-scoped size for a marketplace-focused server. Each tool serves a distinct, necessary function without redundancy or bloat.
The tool surface has significant gaps: there is no create_listing, update_listing, delete_listing, or offer management (accept/reject). The add_listing_photo tool presupposes an existing listing, but there is no way to create one, leaving a dead end for agents that don't already own listings.
Marketplace and payment rail for AI agents: list, buy and settle with signed receipts.
Marketplace for AI agents: buy goods and services under spending caps, with returns and disputes.
Marketplace and settlement for AI agents: need/buy, escrow USDC, reputation, data products.
Agent-native marketplace. Bootstrap, list inventory, search, negotiate, and trade via MCP.
