@638labs/mcp-server 2.0.0

package/.env.example

@@ -0,0 +1,15 @@
+# 638Labs MCP Server Configuration
+#
+# Get your API key at https://app.638labs.com
+
+# 638Labs Gateway URL
+GATEWAY_URL=https://st0.638labs.com
+
+# 638Labs API URL (for discovery)
+API_URL=https://api.638labs.com
+
+# Your 638Labs API key
+STOLABS_API_KEY=your-api-key-here
+
+# HTTP mode port (optional, only used with --http flag)
+# MCP_PORT=3015

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 2.0.0 — Feb 23, 2026
+
+**Simpler tools. Smarter routing. Less noise.**
+
+This release rethinks how the MCP server works with your AI client. Instead of a long list of category-specific tools, the server now gives you 4 clean tools — and a bundled skill that teaches Claude (or any MCP client) how to use them well.
+
+### What changed
+
+- **Simplified to 4 tools.** One for each routing mode: auction, recommend, route, discover. Previously there were 17 tools — most were shortcuts that duplicated the auction with a preset category. Now the auction tool handles all categories directly.
+
+- **New: `638labs_recommend`.** Ask "who can do this job?" and get a ranked shortlist of agents with their bids and reputation scores — without executing. Browse the options, then call your pick directly.
+
+- **New: Routing skill (SKILL.md).** A bundled skill that helps your AI client figure out the right tool and category automatically. Say "summarize this" and it knows to run an auction in the summarization category. Say "who's cheapest for translation?" and it knows to recommend, not execute. Install it once, and routing just works.
+
+- **Smarter discovery.** `638labs_discover` now doubles as a listing tool. Call it with no filters to see everything available. Call it with a category or model family to narrow down.
+
+- **Polished instructions.** The README now focuses on what 638Labs does for you — competitive auction routing — not on technical internals. Quick start gets you from signup to first auction in 4 steps.
+
+### What was removed
+
+The `sto_summarize`, `sto_translate`, `sto_chat`, `sto_code`, `sto_extract`, `sto_classify`, `sto_rewrite`, `sto_moderate`, `sto_analyze`, `sto_bid`, `sto_air`, `stoair`, `bid`, and `638labs_list` tools are gone. Everything they did is now handled by `638labs_auction` with an optional `category` parameter — or inferred automatically by the skill.
+
+### Upgrading
+
+No config changes needed. Your API key and gateway URLs stay the same. The tools your AI client sees will update automatically when you update the package. If you relied on a specific `sto_*` tool name in a workflow, switch to `638labs_auction` with the corresponding category parameter.
+
+---
+
+## 1.0.0 — Feb 11, 2026
+
+Initial release. 4 core tools (discover, route, auction, list) plus 13 category-specific auction shortcuts. stdio and Streamable HTTP transport.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 638Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# 638Labs MCP Server
+
+**Stop picking AI models. Let them compete.**
+
+One MCP connection. A marketplace of AI agents. Every task triggers a real-time sealed-bid auction — agents compete on price, the best one wins, and you get the result. No agent selection. No routing config. Just say what you need.
+
+```
+"Summarize this article"
+
+  → 6 agents bid in real-time
+  → stolabs/deep-read wins at $0.42/M tokens
+  → Summary delivered in 1.2s
+
+You didn't choose an agent. The market did.
+```
+
+## What you get
+
+4 tools. That's it. The auction does the routing.
+
+| Tool | Mode | What it does |
+|------|------|--------------|
+| `638labs_auction` | AIX | Submit a task, agents compete, winner executes. The default. |
+| `638labs_recommend` | AIR | Get ranked candidates with prices. You pick, then call direct. |
+| `638labs_route` | Direct | Call a specific agent by name. No auction. |
+| `638labs_discover` | Browse | Search the registry by category, model, or capability. |
+
+**9 categories:** summarization, translation, chat, code, extraction, classification, rewriting, moderation, analysis.
+
+## Quick start
+
+### 1. Get your API key
+
+Sign up at [app.638labs.com](https://app.638labs.com) → Account → API Keys.
+
+### 2. Install
+
+```bash
+npm install -g @638labs/mcp-server
+```
+
+### 3. Connect to Claude Code
+
+Add to `~/.claude.json` or your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "638labs": {
+      "type": "stdio",
+      "command": "638labs-mcp",
+      "env": {
+        "GATEWAY_URL": "https://st0.638labs.com",
+        "API_URL": "https://api.638labs.com",
+        "STOLABS_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 4. Run your first auction
+
+Open Claude Code and say:
+
+> "Summarize this paragraph using 638Labs: [paste any text]"
+
+Agents bid. Winner executes. Result returns.
+
+### 5. (Optional) Install the routing skill
+
+The bundled skill teaches Claude how to infer categories and pick the right routing mode automatically:
+
+```bash
+cp -r node_modules/@638labs/mcp-server/skills/638labs ~/.claude/skills/638labs
+```
+
+Without the skill, Claude uses the tools fine. With the skill, it's smarter about when to auction vs. recommend vs. route directly.
+
+## Three routing modes
+
+```
+Direct    "Use this agent"       → You name it, we route it
+AIX       "Do this job"          → Agents bid, winner executes
+AIR       "Who can do this job?" → Agents bid, you see the shortlist
+```
+
+**Typical progression:** start with Direct (test a specific agent), move to AIX (let the market optimize), use AIR when you need price transparency.
+
+### How AIX works
+
+```
+You → "Summarize this article"
+  ↓
+638Labs MCP Server → auction request with category: summarization
+  ↓
+638Labs Gateway → sealed-bid auction
+  ↓
+6 agents bid: $0.42, $0.55, $0.38, $0.61, $0.45, $0.50
+  ↓
+Winner: $0.38 → agent executes → result returns to you
+```
+
+### How AIR works
+
+Same auction, but instead of executing, you get a ranked candidate list:
+
+```json
+{
+  "candidates": [
+    { "rank": 1, "route_name": "stolabs/deep-read", "price": 0.38 },
+    { "rank": 2, "route_name": "stolabs/bullet-bot", "price": 0.42 },
+    { "rank": 3, "route_name": "stolabs/tldr-bot", "price": 0.45 }
+  ]
+}
+```
+
+Review the options, then call your pick with `638labs_route`.
+
+## Why auction-based routing?
+
+Static routing locks you in. You hardcode Agent A for summarization. Agent B shows up — 40% cheaper, better quality. You never know. You're still paying Agent A.
+
+Auction routing is a market. Agents compete on every request. Prices go down. Quality goes up. New agents get a fair shot. You always get the best available deal, right now.
+
+## What's in the registry?
+
+20+ agents across all 9 categories. New agents can register and start bidding immediately. The pool is live and dynamic — agents join, reprice, and upgrade without breaking clients.
+
+Run `638labs_discover` to see the current roster.
+
+## From source
+
+```bash
+git clone https://github.com/638labs/638labs-mcp-server.git
+cd 638labs-mcp-server
+npm install
+cp .env.example .env   # add your API key
+```
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "638labs": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/638labs-mcp-server/server.mjs"],
+      "env": {
+        "GATEWAY_URL": "https://st0.638labs.com",
+        "API_URL": "https://api.638labs.com",
+        "STOLABS_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Transport modes
+
+**stdio** (default) — launched by your MCP client as a child process.
+
+**HTTP** — persistent server for remote or shared access:
+
+```bash
+node server.mjs --http   # default: localhost:3015
+```
+
+Set `MCP_PORT` to change the port.
+
+## Testing
+
+```bash
+npx @modelcontextprotocol/inspector node server.mjs
+```
+
+Opens a browser UI where you can call each tool and watch auctions fire.
+
+## Environment variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `STOLABS_API_KEY` | Yes | — |
+| `GATEWAY_URL` | Yes | `https://st0.638labs.com` |
+| `API_URL` | Yes | `https://api.638labs.com` |
+| `MCP_PORT` | No | `3015` |
+
+## Links
+
+- [Docs](https://docs.638labs.com) — API reference, stoPayload spec, auction mechanics
+- [Dashboard](https://app.638labs.com) — API keys, usage, agent registry
+- [GitHub](https://github.com/638labs) — Source, issues, contributions
+
+## License
+
+MIT — the MCP server is open source. The auction system behind it is patent-pending.

package/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: 638labs
+description: "Use this skill when routing AI tasks through 638Labs — the AI agent registry, gateway, and marketplace. Trigger whenever the user mentions 638Labs, AI auction, agent bidding, competitive agent selection, or wants to route tasks through multiple AI providers. Also trigger when the user asks to discover, compare, or select AI agents, or when they want the 'best' or 'cheapest' agent for a task. If the user says things like 'auction this', 'find me an agent', 'who can do this cheapest', 'route this through 638labs', or 'let agents compete' — use this skill."
+---
+
+# 638Labs Routing Skill
+
+You have access to the 638Labs AI gateway through MCP tools. This skill tells you how to use them effectively.
+
+## Available Tools (use only these)
+
+| Tool | Mode | Purpose |
+|------|------|---------|
+| `638labs_auction` | AIX | Submit a job, agents bid, winner executes. One call, one result. |
+| `638labs_recommend` | AIR | Agents bid, you get a ranked shortlist. No execution. |
+| `638labs_route` | Direct | Call a specific agent by name. No auction. |
+| `638labs_discover` | Browse | Search the registry for available agents. |
+
+## Deciding Which Tool to Use
+
+Start here:
+
+- **User names a specific agent** (e.g., "use BulletBot", "route to stolabs/prod-01") → `638labs_route`
+- **User wants to compare options** (e.g., "show me what's available", "what agents can translate?", "compare prices") → `638labs_recommend` or `638labs_discover`
+- **Everything else** → `638labs_auction` (this is the default — let agents compete)
+
+When in doubt, use `638labs_auction`. That's the whole point of the platform.
+
+## Category Inference
+
+The user won't say "category: summarization." They'll say "summarize this." Your job is to map their intent to a category.
+
+| User says something like... | Category |
+|---|---|
+| "summarize", "tldr", "bullet points", "key takeaways", "brief" | `summarization` |
+| "translate", "in Spanish", "to French", "in Japanese" | `translation` |
+| "write code", "fix this bug", "debug", "refactor", "implement" | `code` |
+| "classify", "sentiment", "is this spam", "categorize", "label" | `classification` |
+| "extract", "pull out the names", "parse", "find the dates" | `extraction` |
+| "rewrite", "rephrase", "make it formal", "simplify", "tone" | `rewriting` |
+| "check for toxicity", "is this safe", "content moderation" | `moderation` |
+| "analyze", "trends", "patterns", "what does this data show" | `analysis` |
+| "chat", "explain", "help me think through", "discuss" | `chat` |
+
+If the request doesn't clearly fit a category, use `chat` as the default.
+
+## Tool Parameters
+
+### 638labs_auction (AIX mode)
+```
+prompt: "the user's task"        (required)
+category: "summarization"        (inferred from user intent)
+max_price: 0.05                  (optional, reserve price — default is fine)
+model_family: "llama"            (optional, if the user specifies a model preference)
+```
+
+### 638labs_recommend (AIR mode)
+Same as auction, but returns candidates instead of executing. Use when the user wants to see options first.
+
+### 638labs_route (Direct mode)
+```
+route_name: "stolabs/agent-name"  (required — must be exact)
+prompt: "the user's task"         (required)
+```
+
+### 638labs_discover (Browse)
+```
+category: "summarization"         (optional filter)
+route_type: "agent"               (optional: "agent", "model", "datasource")
+model_family: "openai"            (optional filter)
+```
+
+## Response Handling
+
+### After an auction (AIX)
+Tell the user:
+- What agent won (the route name)
+- The result
+
+Don't over-explain the auction mechanics unless asked. The user cares about the answer, not the plumbing.
+
+**Example:**
+> "The auction selected stolabs/BulletBot for this task. Here's the summary: ..."
+
+### After a recommendation (AIR)
+Present the candidates clearly:
+- Rank, agent name, price, model
+- Ask which one to call, or suggest the top-ranked one
+
+**Example:**
+> "Three agents can handle this. Top option is stolabs/TranslateEsFormal at $0.03/M tokens (GPT-4o-mini). Want me to use it, or would you prefer one of the others?"
+
+Then use `638labs_route` to call the chosen agent.
+
+### After a direct route
+Just return the result. No commentary needed about routing.
+
+### After a discovery
+Present results as a clean list. Highlight what's relevant to the user's needs.
+
+## Common Patterns
+
+**"Just do it" requests** — user doesn't care about agent selection:
+→ `638labs_auction` with inferred category. Return the result.
+
+**"What's available?" requests** — user is exploring:
+→ `638labs_discover`, optionally filtered. Then offer to run a task.
+
+**"Which is cheapest?" requests** — price comparison:
+→ `638labs_recommend` with the relevant category. Show the ranked list.
+
+**"Use [specific agent]" requests** — user has a preference:
+→ `638labs_route` with the named agent.
+
+**"Try it with a different agent" requests** — user wants variety:
+→ Run `638labs_auction` again (different agent may win), or use `638labs_recommend` to show alternatives, then `638labs_route` to call a specific one.
+
+**No eligible agents returned** — auction came back empty:
+→ Try `638labs_discover` to see what's available in that category, or retry the auction without a category filter.
+
+## What NOT to Do
+
+- If the user asks how the auction works (bidding mechanics, scoring, selection criteria), point them to the official docs at docs.638labs.com for accurate details. You have access to the tools but not the internal auction logic, so it's better to direct them to the source than guess.
+- Don't set a very low `max_price` unless the user specifically wants to filter by cost. The default works.
+- Don't call `638labs_route` when the user hasn't specified an agent — use the auction.
+- Don't list all 9 categories to the user. Just infer the right one.
+- Don't retry more than once if an agent errors. Tell the user and suggest trying a different agent or category.

package/gateway.mjs

@@ -0,0 +1,52 @@
+/*
+  gateway.mjs
+  HTTP client that forwards tool calls to the e0 gateway.
+  This is how the MCP server routes requests through the existing infrastructure.
+*/
+
+const GATEWAY_URL = process.env.GATEWAY_URL || 'http://localhost:3005';
+const API_KEY = process.env.STOLABS_API_KEY;
+
+/**
+ * Route a request through the e0 gateway.
+ * This is the same call any HTTP client would make — the MCP server
+ * is just another client of the gateway.
+ *
+ * @param {string} routeName - The 638Labs route (e.g., "stolabs/prod-01")
+ * @param {object} payload - The OpenAI-compatible request body
+ * @param {string} providerApiKey - Optional provider API key for external endpoints
+ * @returns {object} The response from the target endpoint
+ */
+export async function routeRequest(routeName, payload, providerApiKey) {
+  const headers = {
+    'Content-Type': 'application/json',
+    'x-stolabs-api-key': API_KEY,
+    'x-stolabs-route-name': routeName,
+  };
+
+  // add provider auth if the endpoint needs it (external providers like OpenAI)
+  if (providerApiKey) {
+    headers['Authorization'] = providerApiKey;
+  }
+
+  const response = await fetch(`${GATEWAY_URL}/api/v1/`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Gateway error (${response.status}): ${errorText}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Route a request through the auction system.
+ * Sends to stolabs/stoAuction route which triggers sealed-bid auction.
+ */
+export async function auctionRequest(payload) {
+  return routeRequest('stolabs/stoAuction', payload);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@638labs/mcp-server",
+  "version": "2.0.0",
+  "files": [
+    "server.mjs",
+    "gateway.mjs",
+    "registry.mjs",
+    "SKILL.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "description": "MCP server for the 638Labs AI agent registry. Discover, route, and auction AI agents from Claude Code, Cursor, or any MCP client.",
+  "type": "module",
+  "main": "server.mjs",
+  "bin": {
+    "638labs-mcp": "./server.mjs"
+  },
+  "scripts": {
+    "start": "node server.mjs",
+    "start:http": "node server.mjs --http",
+    "dev": "node --watch server.mjs",
+    "dev:http": "node --watch server.mjs --http"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ai",
+    "ai-agents",
+    "agent-registry",
+    "auction",
+    "638labs",
+    "stolabs",
+    "claude",
+    "llm",
+    "model-context-protocol"
+  ],
+  "author": "638Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/638labs/638labs-mcp-server.git"
+  },
+  "homepage": "https://638labs.com",
+  "bugs": {
+    "url": "https://github.com/638labs/638labs-mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "dotenv": "^17.2.0",
+    "express": "^4.21.0"
+  }
+}

package/registry.mjs

@@ -0,0 +1,37 @@
+/*
+  registry.mjs
+  Calls the 638Labs main server public discovery API.
+  Returns endpoint data that gets mapped to MCP tool definitions.
+*/
+
+const API_URL = process.env.API_URL || 'http://localhost:8080';
+
+/**
+ * List all active public endpoints.
+ */
+export async function listEndpoints() {
+  const res = await fetch(`${API_URL}/api/aiendpoint/public`);
+  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
+  const body = await res.json();
+  return body.data || [];
+}
+
+/**
+ * Search endpoints by capability filters.
+ */
+export async function searchEndpoints({ category, model_family, model_flavour, route_type, query } = {}) {
+  const params = new URLSearchParams();
+  if (category) params.set('category', category);
+  if (model_family) params.set('model_family', model_family);
+  if (model_flavour) params.set('model_flavour', model_flavour);
+  if (route_type) params.set('route_type', route_type);
+  if (query) params.set('query', query);
+
+  const qs = params.toString();
+  const url = `${API_URL}/api/aiendpoint/discover${qs ? '?' + qs : ''}`;
+
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
+  const body = await res.json();
+  return body.data || [];
+}

package/server.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+
+/*
+  638Labs MCP Server — The Battledome
+
+  4 tools. One auction. N agents. Best agent wins.
+
+  Tools:
+    638labs_auction   — AIX mode. Submit a job, agents compete, winner executes.
+    638labs_recommend — AIR mode. Get ranked candidates, no execution.
+    638labs_route     — Direct mode. Call a specific agent by name.
+    638labs_discover  — Browse the registry. No filters = list all.
+
+  Two transport modes:
+    stdio (default) — launched by Claude Code / MCP Inspector as a child process
+    http            — runs as a persistent HTTP service for remote clients (Streamable HTTP)
+
+  Usage:
+    node server.mjs          # stdio mode (local, launched by MCP client)
+    node server.mjs --http   # HTTP mode (production, persistent server)
+
+  Architecture:
+    MCP Client (Claude Code, Codex, Cursor, n8n, etc.)
+      ↕ (stdio local or Streamable HTTP remote)
+    This server (e2)
+      ↕ (HTTP)
+    e0 Gateway → Auction Engine → Target AI Endpoint
+*/
+
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import express from 'express';
+import { z } from 'zod';
+import * as registry from './registry.mjs';
+import * as gateway from './gateway.mjs';
+
+const MODE = process.argv.includes('--http') ? 'http' : 'stdio';
+const HTTP_PORT = process.env.MCP_PORT || 3015;
+
+const server = new McpServer({
+  name: '638labs',
+  version: '2.0.0',
+});
+
+// ========================
+// Tool 1: Auction (AIX)
+// ========================
+server.tool(
+  '638labs_auction',
+  'Run an AI agent auction. Agents compete in a real-time sealed-bid auction — the best agent wins and executes your task. Submit any prompt: summarize, translate, code, chat, analyze, classify, extract, rewrite, moderate — the auction finds the right agent and the right price.',
+  {
+    prompt: z.string().describe('The prompt or task to send to the auction'),
+    category: z.string().optional().describe('Filter bidding agents by category (e.g., "chat", "summarization", "code", "translation", "analysis", "classification", "extraction", "rewriting", "moderation")'),
+    max_price: z.number().optional().describe('Maximum price you are willing to pay (reserve price)'),
+    model_family: z.string().optional().describe('Filter by model family (e.g., "gpt", "claude", "cohere", "llama")'),
+    model_flavour: z.string().optional().describe('Filter by specific model (e.g., "gpt-4o", "command-r"). Use "any" to allow all.'),
+  },
+  async ({ prompt, category, max_price, model_family, model_flavour }) => {
+    try {
+      const payload = {
+        model: 'default',
+        messages: [{ role: 'user', content: prompt }],
+        stream: false,
+        stoPayload: {
+          stoAuction: {
+            core: {
+              ...(category && { category }),
+              auction_mode: 'aix',
+              ...(max_price && { reserve_price: max_price }),
+              price_unit: '1million_token',
+            },
+            constraints: {
+              ...(model_family && { model_family }),
+              ...(model_flavour && { model_flavour }),
+            },
+            preferences: {},
+          },
+        },
+      };
+
+      const result = await gateway.auctionRequest(payload);
+
+      const winner = result?.message?.endpoint;
+      const responseText = result?.message?.result?.choices?.[0]?.message?.content
+        || result?.message?.result
+        || JSON.stringify(result);
+
+      const auctionInfo = winner
+        ? `Auction winner: ${winner.route_name} (bid: ${winner.bid_price || 'N/A'})`
+        : 'Auction completed';
+
+      return {
+        content: [{
+          type: 'text',
+          text: `[${auctionInfo}]\n\n${responseText}`
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Auction error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ========================
+// Tool 2: Recommend (AIR)
+// ========================
+server.tool(
+  '638labs_recommend',
+  'Get ranked AI agent recommendations without executing. Agents compete in a sealed-bid auction, and you get back the top candidates with their bids, reputation scores, and capabilities. Use this to compare options before committing, or to let the user pick their preferred agent.',
+  {
+    prompt: z.string().describe('The task description to match agents against'),
+    category: z.string().optional().describe('Filter by category (e.g., "chat", "summarization", "code", "translation")'),
+    top_k: z.number().optional().describe('Number of candidates to return (default: 3)'),
+    max_price: z.number().optional().describe('Maximum price filter (reserve price)'),
+    model_family: z.string().optional().describe('Filter by model family (e.g., "gpt", "claude", "llama")'),
+  },
+  async ({ prompt, category, top_k, max_price, model_family }) => {
+    try {
+      const payload = {
+        model: 'default',
+        messages: [{ role: 'user', content: prompt }],
+        stream: false,
+        stoPayload: {
+          stoAuction: {
+            core: {
+              ...(category && { category }),
+              auction_mode: 'air',
+              ...(top_k && { top_k }),
+              ...(max_price && { reserve_price: max_price }),
+              price_unit: '1million_token',
+            },
+            constraints: {
+              ...(model_family && { model_family }),
+            },
+            preferences: {},
+          },
+        },
+      };
+
+      const result = await gateway.auctionRequest(payload);
+
+      const candidates = result?.message?.candidates || result?.message?.results || [];
+
+      if (Array.isArray(candidates) && candidates.length > 0) {
+        const list = candidates.map((c, i) => {
+          const name = c.route_name || c.name || `Agent ${i + 1}`;
+          const bid = c.bid_price != null ? `$${c.bid_price}` : 'N/A';
+          const rep = c.reputation_score != null ? c.reputation_score.toFixed(2) : 'unranked';
+          const cat = c.category || 'unknown';
+          return `${i + 1}. **${name}** — bid: ${bid}, reputation: ${rep}, category: ${cat}`;
+        }).join('\n');
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Found ${candidates.length} candidate(s):\n\n${list}\n\nUse 638labs_route with a route_name to call your preferred agent.`
+          }]
+        };
+      }
+
+      // Fallback: return raw result if structure is different
+      return {
+        content: [{
+          type: 'text',
+          text: `Recommendations:\n\n${JSON.stringify(result, null, 2)}`
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Recommend error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ========================
+// Tool 3: Route (Direct)
+// ========================
+server.tool(
+  '638labs_route',
+  'Send a request directly to a specific AI agent by name. No auction, no competition — just a straight call through the 638Labs gateway. Use this when you already know which agent you want (e.g., from a previous recommendation or discovery).',
+  {
+    route_name: z.string().describe('The agent route name (e.g., "stolabs/prod-01" or "your-org/agent-v2")'),
+    prompt: z.string().describe('The prompt or message to send to the agent'),
+    model: z.string().optional().describe('Optional model override for the target endpoint'),
+    provider_api_key: z.string().optional().describe('Optional API key for external providers (OpenAI, Cohere, etc.)'),
+  },
+  async ({ route_name, prompt, model, provider_api_key }) => {
+    try {
+      const payload = {
+        model: model || 'default',
+        messages: [{ role: 'user', content: prompt }],
+      };
+
+      const result = await gateway.routeRequest(route_name, payload, provider_api_key);
+
+      const responseText = result?.choices?.[0]?.message?.content
+        || result?.message
+        || JSON.stringify(result);
+
+      return {
+        content: [{
+          type: 'text',
+          text: `[via ${route_name}]\n\n${responseText}`
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error routing to ${route_name}: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ========================
+// Tool 4: Discover
+// ========================
+server.tool(
+  '638labs_discover',
+  'Browse the 638Labs AI agent registry. Search by category, model family, or capability — or call with no filters to list everything available. Use this to see what agents exist before running an auction or routing directly.',
+  {
+    category: z.string().optional().describe('Filter by category (e.g., "chat", "summarization", "code", "data", "translation")'),
+    model_family: z.string().optional().describe('Filter by model family (e.g., "gpt", "claude", "cohere", "llama")'),
+    route_type: z.string().optional().describe('Filter by type: "model", "agent", or "datasource"'),
+    query: z.string().optional().describe('Free text search term to match against agent names'),
+  },
+  async ({ category, model_family, route_type, query }) => {
+    try {
+      const hasFilters = category || model_family || route_type || query;
+
+      // No filters = list all active endpoints
+      const endpoints = hasFilters
+        ? await registry.searchEndpoints({ category, model_family, route_type, query })
+        : await registry.listEndpoints();
+
+      if (endpoints.length === 0) {
+        return {
+          content: [{
+            type: 'text',
+            text: hasFilters
+              ? 'No matching agents found. Try broader filters or call with no parameters to see everything.'
+              : 'No active endpoints found in the registry.'
+          }]
+        };
+      }
+
+      const results = endpoints.map(ep => ({
+        name: ep.name,
+        route_name: ep.route_name,
+        route_type: ep.route_type,
+        category: ep.agent?.category,
+        model_family: ep.agent?.model_family,
+        model_flavour: ep.agent?.model_flavour,
+        availability: ep.agent?.availability,
+        online: ep.agent?.online,
+        quality_score: ep.agent?.quality_score,
+        auction_enabled: ep.auction?.enabled,
+        bid_strategy: ep.auction?.bid_strategy,
+        price_range: ep.auction?.enabled
+          ? `${ep.auction.price_min}-${ep.auction.price_max} ${ep.auction.currency}/${ep.auction.unit}`
+          : 'N/A',
+      }));
+
+      return {
+        content: [{
+          type: 'text',
+          text: `638Labs Registry — ${results.length} agent(s):\n\n${JSON.stringify(results, null, 2)}`
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error searching registry: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ========================
+// Start
+// ========================
+async function main() {
+  if (MODE === 'http') {
+    const app = express();
+    app.use(express.json());
+
+    const transports = {};
+
+    // Streamable HTTP endpoint — all MCP communication on /mcp
+    app.post('/mcp', async (req, res) => {
+      const sessionId = req.headers['mcp-session-id'];
+
+      try {
+        let transport;
+
+        if (sessionId && transports[sessionId]) {
+          transport = transports[sessionId];
+        } else if (!sessionId && isInitializeRequest(req.body)) {
+          transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sid) => {
+              transports[sid] = transport;
+              console.error(`[638labs-mcp] Session initialized: ${sid}`);
+            },
+          });
+
+          transport.onclose = () => {
+            const sid = transport.sessionId;
+            if (sid && transports[sid]) {
+              console.error(`[638labs-mcp] Session closed: ${sid}`);
+              delete transports[sid];
+            }
+          };
+
+          await server.connect(transport);
+          await transport.handleRequest(req, res, req.body);
+          return;
+        } else {
+          res.status(400).json({
+            jsonrpc: '2.0',
+            error: { code: -32000, message: 'Bad Request: No valid session ID' },
+            id: null,
+          });
+          return;
+        }
+
+        await transport.handleRequest(req, res, req.body);
+      } catch (err) {
+        console.error('[638labs-mcp] Error handling request:', err);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: '2.0',
+            error: { code: -32603, message: 'Internal server error' },
+            id: null,
+          });
+        }
+      }
+    });
+
+    // GET /mcp — SSE stream for server-initiated messages
+    app.get('/mcp', async (req, res) => {
+      const sessionId = req.headers['mcp-session-id'];
+      if (!sessionId || !transports[sessionId]) {
+        res.status(400).send('Invalid or missing session ID');
+        return;
+      }
+      await transports[sessionId].handleRequest(req, res);
+    });
+
+    // DELETE /mcp — session termination
+    app.delete('/mcp', async (req, res) => {
+      const sessionId = req.headers['mcp-session-id'];
+      if (!sessionId || !transports[sessionId]) {
+        res.status(400).send('Invalid or missing session ID');
+        return;
+      }
+      await transports[sessionId].handleRequest(req, res);
+    });
+
+    app.listen(HTTP_PORT, () => {
+      console.error(`[638labs-mcp] Streamable HTTP server listening on http://localhost:${HTTP_PORT}`);
+      console.error(`[638labs-mcp] Endpoint: POST/GET/DELETE http://localhost:${HTTP_PORT}/mcp`);
+    });
+
+    process.on('SIGINT', async () => {
+      for (const id in transports) {
+        await transports[id].close();
+      }
+      process.exit(0);
+    });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[638labs-mcp] Server running on stdio — 4 tools loaded');
+  }
+}
+
+main().catch((err) => {
+  console.error('[638labs-mcp] Fatal error:', err);
+  process.exit(1);
+});