Web-MCP Documentation

Integrate AI agents with BidDirect auctions using the Model Context Protocol

MCP Endpoint:https://api.bid.direct/mcp

Authentication

AI agents must authenticate using email and password only. Google OAuth requires browser redirects that agents cannot follow.

The authentication flow returns a session ID that must be included as an x-session-id header in all subsequent MCP and API calls. Sessions last 24 hours and auto-extend on use.

Step 1: Log in

curl -X POST https://api.bid.direct/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your-password"
  }'

Step 2: Extract session ID from response

{
  "user": { "uid": "...", "email": "..." },
  "sessionId": "abc123-session-id"
}

Step 3: Include session ID in MCP calls

# All MCP tool calls include this header:
x-session-id: abc123-session-id

Quick Start

Connect

Add https://api.bid.direct/mcp as a remote MCP server in your AI client.

Authenticate

Call Tools

Start with biddirect.health, then use biddirect.buyer.* or biddirect.seller.* tools.

Client Setup Guides

Goose AI Agent

Open Goose MCP settings, add a remote server, and paste the configuration above. Replace <your-session-id> with the session ID from authentication.

{
  "mcpServers": {
    "biddirect": {
      "type": "remote",
      "url": "https://api.bid.direct/mcp",
      "headers": {
        "x-session-id": "<your-session-id>"
      }
    }
  }
}

OpenAI Agents

Add this MCP connector to your OpenAI agent configuration. The session ID header authenticates all tool calls.

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "biddirect",
      "server_url": "https://api.bid.direct/mcp",
      "headers": {
        "x-session-id": "<your-session-id>"
      }
    }
  ]
}

Gemini

Open Gemini MCP tool settings, add a remote MCP server, and use the configuration above.

{
  "mcpServers": {
    "biddirect": {
      "url": "https://api.bid.direct/mcp",
      "headers": {
        "x-session-id": "<your-session-id>"
      }
    }
  }
}

Claude Desktop

Add this entry to your Claude Desktop MCP configuration file (Settings > Developer > Edit Config).

{
  "mcpServers": {
    "biddirect": {
      "url": "https://api.bid.direct/mcp",
      "headers": {
        "x-session-id": "<your-session-id>"
      }
    }
  }
}

Tool Namespaces

`biddirect.health`

Server health check (no auth required)

biddirect.health

`biddirect.buyer.*`

Buyer tools: search auctions, view details, place bids, manage watchlist, buy now, checkout

biddirect.buyer.whoamibiddirect.buyer.auction.searchbiddirect.buyer.auction.getbiddirect.buyer.auction.bidbiddirect.buyer.watchlist.list

`biddirect.seller.*`

Seller tools: create auctions, manage listings, publish, schedule, view analytics

biddirect.seller.whoamibiddirect.seller.auction.createbiddirect.seller.auction.updatebiddirect.seller.auction.publishbiddirect.seller.auction.list

Example Workflows

Buyer Lifecycle

biddirect.buyer.auction.search — Find auctions matching your criteria
biddirect.buyer.auction.get — View full auction details
biddirect.buyer.watchlist.add — Track auctions of interest
biddirect.buyer.auction.bid — Place a bid
biddirect.buyer.payment.checkout — Complete payment after winning

Seller Lifecycle

biddirect.seller.whoami — Verify seller status
biddirect.seller.auction.create — Create a new auction draft
biddirect.seller.auction.update — Add details, images, pricing
biddirect.seller.auction.publish — Go live or schedule
biddirect.seller.auction.list — Monitor your active auctions

Advanced MCP Capabilities

`resources/*`

Read auction and user resource URIs such as auctions://live and auction://{id}/state.

`sampling/createMessage`

Request bidding-strategy sampling guidance from the MCP server for agent workflows.

`elicitation/create`

Generate bid-confirmation form payloads and secure URL handoff payloads for checkout.

`MCP Apps (ui://app/*.html)`

Tool descriptors include app templates that render BidDirect AI-UI React surfaces in supported clients.

Resources

/mcp

MCP endpoint for AI agents

/llms.txt

Agent-readable documentation

/openapi.json

OpenAPI specification

/mcp-ui-gallery

AI-UI component preview contract

Troubleshooting

401 Unauthorized / Session Expired

Cause: Session ID is missing, invalid, or expired (24h TTL).

Fix: Re-authenticate via POST /v1/auth/login and use the new session ID.

403 Forbidden

Cause: Your account lacks the required role. For example, seller tools require approved seller status.

Fix: Check your account status with biddirect.buyer.whoami or biddirect.seller.whoami.

400 Bad Request / Validation Error

Cause: Missing or invalid parameters in the tool call.

Fix: Review the tool's inputSchema for required fields and value constraints.

Google OAuth Not Working

Cause: Google OAuth requires browser redirects that AI agents cannot follow.

Fix: Use email/password authentication only. Register an account with email/password at bid.direct if you only have Google sign-in.