Skip to content

How it works

A practical guide for company owners and agent builders.

1. What this is

The AiVironment Marketplace is a directory of B2B suppliers, manufacturers, and service providers built so AI agents can find them and route real work — quotes, sourcing, partnerships — without scraping HTML or guessing at email addresses.

Two audiences, one directory:

2. What is MCP?

MCP — the Model Context Protocol — is an open standard from Anthropic that lets AI clients (Claude, ChatGPT, Cursor, custom agents) plug into external tools the same way browsers plug into web servers. The client speaks a common protocol over HTTP; the server exposes a typed list of tools, takes calls, and returns structured results.

The Marketplace runs an MCP server at https://mcp.marketplace.aivironment.ai/mcp (Streamable HTTP transport, Bearer-token auth). It exposes three tools:

  1. marketplace_search_companies — ranked search by query + filters
  2. marketplace_get_company — full profile by slug
  3. marketplace_request_quote — submit a contact / quote request

The model decides when to call them. You don't write code; you write prompts, and a model that has these tools available will reach for them when the task fits — “find me a…”, “get a quote from…”, etc.

3. The data model

The directory is built around four entities:

Search runs a hybrid of PostgreSQL full-text search and pgvector semantic similarity (when the OpenAI key is configured), fused with Reciprocal Rank Fusion. Premium listings get a placement boost.

4. For company owners (UI)

End-to-end flow for a human listing their company:

  1. Sign in. Click List your company on the home page or go to /login. Sign in with Google — that's the only auth provider. We use Google's assertion that your email is verified.
  2. Create your company. First-time users land on /dashboard/new-company. Fill in name, slug (auto-derived from the name), country, tagline, description, website. The signed-in user becomes the owner.
  3. Add offerings. In the dashboard Offerings tab, list each product or service: type (product / service), name, optional description, optional price label. There's no limit.
  4. Polish the profile. The Profile tab lets you edit anything searchable — tagline, description, certifications, keywords, industry. Edits trigger a re-embedding of the company so semantic search finds you under the new wording within seconds.
  5. Watch the inbox. The Inbox tab shows quote requests as they arrive. Each entry has the requester's name, email, optional company, the message, and an optional budget label. Mark items viewed, replied, or closed. We do not send email notifications today — check the dashboard.
  6. Get reviews. Customers can leave reviews from your public profile page. Reviews show up in your Reviews tab including any with verification metadata.

You can manage multiple companies under one account. Cross-tenant access is blocked — trying to view another company's dashboard returns 404, never 403, so company existence isn't leaked.

5. For agent builders (MCP)

Wire the MCP server into your client. The actual setup snippets for Claude Code, Claude Desktop, Claude.ai, and ChatGPT live on the integrations page. What follows is what to do once it's connected.

Get a personal token

The MCP endpoint requires a Bearer token. Generate one yourself in Dashboard → MCP tokens after signing in. Tokens are prefixed aiv_mcp_, scoped per tool (mcp:search, mcp:get_company, mcp:request_quote), expirable (30 / 90 / 365 days, default 90), and revocable any time. The raw value is shown only once at creation — copy it before navigating away.

Typical 3-step workflow

  1. Search. marketplace_search_companies with a natural-language query plus any structured filters (country, industry, certification). Returns up to 20 ranked candidates per page.
  2. Read. marketplace_get_company with the slug from a search result. Returns the full profile — description, all offerings, public contact methods, review summary.
  3. Request. marketplace_request_quote with the company UUID, your user's contact details, and a specific message. Lands in the company's dashboard inbox.

What good prompts look like

The model decides when to invoke tools. The shape of your prompt shapes the calls it makes. A good agent-style prompt:

Find me three EU-based ISO 9001 certified industrial robotics
integrators that do cobotic cells for SMB manufacturers. For each
candidate, summarise their core offering and any certifications,
then ask the top one for a quote on a 4-cell pilot project.

This will typically produce: one or two marketplace_search_companies calls (the model may refine the query if the first returns nothing), then a marketplace_get_company on the top hit, then a marketplace_request_quote if the user has confirmed.

Anatomy of a quote request

python
marketplace_request_quote(
  company_id="d474f6f5-c900-45e6-a99f-22466bd37f0d",
  requester_name="Alex Chen, AI buying agent for Buildco",
  requester_email="alex@buildco.example",
  message="Looking for 200 hydraulic valves, 1/2 inch NPT, "
          "ISO 9001 supply chain. Delivery to Bydgoszcz Q3.",
  budget_label="€20k–€40k"
)
  • company_id — UUID from search results, not the slug. The slug is for marketplace_get_company.
  • requester_email is where the company will reply directly — agents acting on behalf of a human user should pass that human's email, not their own.
  • message should be specific: quantities, specs, timeline, location. Vague messages get ignored.

6. Prompt examples

Things that work well via the MCP-connected client:

7. Limits and trust