---
name: bizclaw
version: 1.0.0
description: The Business Layer for AI Agents — discover, search, and connect with real-world companies
emoji: 📡
homepage: https://bizclaw.xyz
category: business-directory
api_base: https://bizclaw.xyz/api/v1/agent
mcp_endpoint: https://bizclaw.xyz/mcp
ucp_profile: https://bizclaw.xyz/.well-known/ucp
agent_skill: https://bizclaw.xyz/skills/bizclaw-agent-workflows/SKILL.md
auth: optional X-API-Key connection header or api_key tool argument (for proposals), none (for search/browse)
---

# BizClaw

> BizClaw is an AI-accessible business directory where AI agents can discover, search, and retrieve structured information about real-world companies. Think of it as a business intelligence layer — search by natural language, filter by category/country/industry, and get complete company profiles with contact details, pricing, features, and more.

## Quick Start

### MCP Integration (Recommended)

Add to your MCP client config:

```json
{
  "mcpServers": {
    "bizclaw": {
      "url": "https://bizclaw.xyz/mcp"
    }
  }
}
```

For Claude Code:
```bash
claude mcp add -s user --transport streamable-http bizclaw https://bizclaw.xyz/mcp
```

Direct JSON-RPC over HTTP (advanced clients):
```http
POST https://bizclaw.xyz/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_companies","arguments":{"query":"logistics in Istanbul"}}}
```

Notes:
- The `Accept` header must include both `application/json` and `text/event-stream`.
- Responses are sent as SSE (`event: message` + `data: ...`).

### UCP Discovery

BizClaw publishes a Universal Commerce Protocol profile for agent discovery:

```text
https://bizclaw.xyz/.well-known/ucp
```

The UCP profile advertises BizClaw's business directory and proposal capabilities under the `xyz.bizclaw.directory.*` namespace. BizClaw is not a shopping cart or checkout provider, so it does not advertise `dev.ucp.shopping.*` capabilities.

UCP-aware MCP clients can include request metadata:

```json
{
  "meta": {
    "ucp-agent": {
      "profile": "https://agent.example/.well-known/ucp"
    }
  }
}
```

When this metadata is present, BizClaw validates the caller profile and includes negotiated `ucp` metadata in tool responses. Existing MCP clients can continue calling tools without `meta`.

### Agent Skill

For workflow guidance, use the BizClaw Agent Workflows skill:

```text
https://bizclaw.xyz/skills/bizclaw-agent-workflows/SKILL.md
```

This skill teaches agents when to call each BizClaw MCP tool, how to preserve company IDs for follow-up questions, how to handle proposal workflows, and why real active customer emails are required for proposals.

### REST API

Base URL: `https://bizclaw.xyz/api/v1/agent`

No authentication required for search/browse operations.
Proposal operations require an API key (register first).

---

## MCP Tools

### search_companies

Search for companies using natural language queries with optional filters.

```
Tool: search_companies
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Natural language search (e.g. "CRM software for small businesses") |
| `category` | string | no | Filter by category (use `list_categories` to see options) |
| `country` | string | no | Filter by country (e.g. "Turkey", "United States") |
| `city` | string | no | Filter by city (e.g. "Istanbul", "Izmir", "Ankara") |
| `industry` | string | no | Filter by specific industry |
| `service_type` | string | no | `remote` · `local` · `nationwide` · `hybrid` |
| `is_verified` | boolean | no | `true` to return only verified companies |
| `limit` | int | no | Max results 1-20 (default 10) |
| `offset` | int | no | Results to skip for pagination (default 0) |

**Response:**
```json
{
  "companies": [
    {
      "id": "uuid",
      "name": "Company Name",
      "website_url": "https://example.com",
      "category": "Technology",
      "description": "Short description",
      "description_long": "Detailed description",
      "target_audience": "Who they serve",
      "pricing": { "details": "Detailed pricing breakdown..." },
      "location": { "country": "Turkey", "address": "..." },
      "industry": "SaaS",
      "contact": { "email": [], "phone": [], "social_links": {} },
      "features": [{ "name": "...", "description": "..." }],
      "use_cases": ["..."],
      "tags": ["tag1", "tag2"],
      "is_verified": true,
      "clarification_questions": ["What platform do you need first?"],
      "match_score": 85.2,
      "match_sources": ["semantic", "keyword"]
    }
  ],
  "suggested_follow_up_questions": ["What platform do you need first?"],
  "next_step": "Present the shortlist, then ask one concise follow-up question using suggested_follow_up_questions unless the user's constraints are already complete.",
  "total_found": 5,
  "offset": 0,
  "limit": 10,
  "has_more": false,
  "query": "CRM software"
}
```

### get_company

Get the full profile of a specific company by its ID.

```
Tool: get_company
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `company_id` | string | yes | UUID from search results |

Returns complete company profile with all fields listed in Data Model below.

### ask_about_companies

Ask a natural language question and get AI-powered recommendations with matched companies.

```
Tool: ask_about_companies
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | yes | Natural language question (e.g. "Which logistics companies offer cold chain in Istanbul?") |
| `context_company_ids` | list[string] | no | Up to 10 company IDs from previous results for follow-up context |

**Response:**
```json
{
  "question": "Which logistics companies offer cold chain?",
  "answer": "Based on the available data, here are logistics companies...",
  "companies": [ "...full company profiles..." ],
  "total_found": 3
}
```

### list_categories

List all available business categories.

```
Tool: list_categories
```

No parameters. Returns:
```json
{
  "categories": ["Technology", "E-commerce", "Marketplace", "..."],
  "total": 25
}
```

### get_company_by_website

Look up a company by its website URL.

```
Tool: get_company_by_website
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `website_url` | string | yes | Website URL (e.g. "example.com" or "https://example.com") |

Returns the company profile if found, or `{"error": "Company not found for this URL"}`.

---

## Agent Registration & Proposals

### How It Works

1. **Register your agent** → `POST /api/v1/agent/register` (no auth needed)
2. **Get your API key** → Save the `bzcl_sk_...` key securely
3. **Create proposals** → Use the API key to send proposals to verified companies
4. **Track responses** → Companies respond via their dashboard, you poll for updates

### Agent Registration

> **Important:** Register with the owner's real, active email address. Disposable, temporary, fake, or alias-only emails are not allowed. Each email can only have one agent. If you lose your API key, use `POST /api/v1/agent/rotate-key` to get a new one — do NOT register again with a different email.

```
POST /api/v1/agent/register
Content-Type: application/json

{
  "name": "MyAgent",
  "owner_email": "dev@example.com"
}
```

**Response:**
```json
{
  "agent": { "id": "uuid", "name": "MyAgent", ... },
  "api_key": "bzcl_sk_your_key_here",
  "message": "Save this API key securely. It cannot be retrieved later.",
  "usage": {
    "header": "X-API-Key: bzcl_sk_your_key_here",
    "mcp_config": { "mcpServers": { "bizclaw": { "url": "...", "headers": { "X-API-Key": "..." } } } }
  }
}
```

> Security note: Never share real API keys in screenshots, logs, prompts, or public repositories.

### Account Management (REST-only)

These operations are intentionally exposed as REST endpoints (not MCP tools):

- Rotate API key: `POST /api/v1/agent/rotate-key` (requires current `X-API-Key`)
- Update agent profile (name/email): `PUT /api/v1/agent/me` with JSON body `{ "name": "...", "owner_email": "..." }` (requires `X-API-Key`)

### MCP Proposal Tools

Recommended authentication: configure your agent key once on the MCP connection as `X-API-Key`. The `api_key` tool argument remains available as a fallback for clients that cannot send custom MCP headers or for debugging.

#### create_proposal

Send a proposal to a verified company on behalf of a customer.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_key` | string | no | Optional if `X-API-Key` is configured on the MCP connection; otherwise your agent API key (`bzcl_sk_...`) |
| `company_id` | string | yes | UUID of the target company (must be verified) |
| `customer_email` | string | yes | End customer's email |
| `customer_name` | string | yes | End customer's name |
| `description` | string | yes | What the customer needs |
| `proposal_type` | string | no | `standard` or `custom` (default: `custom`) |

#### create_batch_proposals

Send the same proposal to multiple companies at once (max 10).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_key` | string | no | Optional if `X-API-Key` is configured on the MCP connection |
| `company_ids` | list[string] | yes | List of company UUIDs (max 10) |
| `customer_email` | string | yes | End customer's email |
| `customer_name` | string | yes | End customer's name |
| `description` | string | yes | What the customer needs |
| `proposal_type` | string | no | `standard` or `custom` (default: `custom`) |

#### get_my_proposals

Check status and responses for all your proposals.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_key` | string | no | Optional if `X-API-Key` is configured on the MCP connection |
| `status_filter` | string | no | `pending`, `approved`, `rejected`, `responded` (use only if the user explicitly asks for a specific status) |
| `limit` | int | no | Max results (default 50) |
| `offset` | int | no | Pagination offset |

#### reply_to_proposal

Reply to a company's response on a proposal. Creates a conversation thread (ping-pong negotiation). Resets proposal status to `pending` so the company sees the new message.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_key` | string | no | Optional if `X-API-Key` is configured on the MCP connection |
| `proposal_id` | string | yes | UUID of the proposal to reply to |
| `message` | string | yes | Your reply message |

### Proposal Statuses

| Status | Meaning |
|--------|---------|
| `pending` | Sent, waiting for company response |
| `approved` | Company approved the proposal |
| `rejected` | Company declined |
| `responded` | Company sent a custom response (check `companyResponse` field) |

### Proposal Workflow Example

Assumes the MCP connection already includes `X-API-Key: bzcl_sk_...`.

```
1. search_companies("nakliye Istanbul") → find verified companies
2. create_proposal(company_id="uuid", customer_email="ali@example.com", customer_name="Ali", description="3+1 evden eve nakliyat, Kadikoy -> Besiktas, 15 Nisan")
3. get_my_proposals() → check for company response
4. (company responds via dashboard → status changes to "responded")
5. reply_to_proposal(proposal_id="uuid", message="Ambalaj dahil mi? Asansör var binamızda.")
6. (status resets to "pending" → company sees new message → replies again)
7. get_my_proposals() → see latest reply and status
```

---

## REST API Endpoints

All endpoints are under `https://bizclaw.xyz/api/v1/agent`.

### Search Companies

```
GET /api/v1/agent/companies?q=<query>&category=<cat>&country=<country>&limit=<n>
```

| Query Param | Type | Required | Description |
|-------------|------|----------|-------------|
| `q` | string | yes | Search query |
| `category` | string | no | Category filter |
| `country` | string | no | Country filter |
| `city` | string | no | City filter |
| `industry` | string | no | Industry filter |
| `service_type` | string | no | `remote` · `local` · `nationwide` · `hybrid` |
| `is_verified` | boolean | no | `true` to return only verified companies |
| `limit` | int | no | Max results 1-20 (default 10) |
| `offset` | int | no | Results to skip for pagination (default 0) |

### Get Company

```
GET /api/v1/agent/companies/{company_id}
```

### Look Up by URL

```
GET /api/v1/agent/companies/by-url/{website_url}
```

### Ask a Question

```
POST /api/v1/agent/ask?question=<question>
```

### List Categories

```
GET /api/v1/agent/categories
```

### Register Agent (no auth)

```
POST /api/v1/agent/register
Body: { "name": "MyAgent", "owner_email": "dev@example.com" }
```

### Create Proposal (API key required)

```
POST /api/v1/agent/proposals
Header: X-API-Key: bzcl_sk_...
Body: { "company_id": "uuid", "customer_email": "...", "customer_name": "...", "description": "...", "type": "custom" }
```

### Create Batch Proposals (API key required)

```
POST /api/v1/agent/proposals/batch
Header: X-API-Key: bzcl_sk_...
Body: { "company_ids": ["uuid1", "uuid2"], "customer_email": "...", "customer_name": "...", "description": "...", "type": "custom" }
```

### List My Proposals (API key required)

```
GET /api/v1/agent/proposals?limit=50
Header: X-API-Key: bzcl_sk_...
```

### Get Proposal Detail (API key required)

```
GET /api/v1/agent/proposals/{proposal_id}
Header: X-API-Key: bzcl_sk_...
```

### Reply to Proposal (API key required)

```
POST /api/v1/agent/proposals/{proposal_id}/reply
Header: X-API-Key: bzcl_sk_...
Body: { "message": "Can you also include packing materials?" }
```

### Rotate API Key (API key required)

```
POST /api/v1/agent/rotate-key
Header: X-API-Key: bzcl_sk_current_key
```

Generates a new key and immediately invalidates the old one.

### Deactivate Agent (API key required)

```
DELETE /api/v1/agent/me
Header: X-API-Key: bzcl_sk_...
```

Deactivates the agent. Existing proposals remain but no new requests can be made.

---

## Data Model

Each company profile contains:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string (UUID) | Unique company identifier |
| `name` | string | Company name |
| `website_url` | string | Company website |
| `category` | string | Business category |
| `description` | string | Short one-line description |
| `description_long` | string | Detailed description (plain text) |
| `target_audience` | string | Who the company serves |
| `pricing.details` | string | Detailed pricing information |
| `location.country` | string | Country |
| `location.city` | string | City |
| `location.address` | string | Physical address |
| `service_type` | string | `remote` · `local` · `nationwide` · `hybrid` |
| `industry` | string | Specific industry |
| `language` | string | Primary language |
| `legal_name` | string | Registered legal name |
| `founded_year` | string | Year founded |
| `contact.email` | list[string] | Contact emails |
| `contact.phone` | list[string] | Phone numbers |
| `contact.social_links` | object | LinkedIn, Twitter, Facebook, etc. |
| `key_offerings` | string | Main product/service offerings |
| `features` | list[object] | Feature name + description pairs |
| `use_cases` | list[string] | Real-world use case descriptions |
| `tags` | list[string] | Searchable tags |
| `is_verified` | boolean | Verified by BizClaw team |

---

## Categories

25 business categories available:

- Technology
- E-commerce
- Marketplace
- Automotive
- Construction & Real Estate
- Manufacturing
- Retail
- Finance
- Healthcare
- Education
- Media & Entertainment
- Food & Beverage
- Hospitality & Tourism
- Logistics & Transportation
- Energy & Utilities
- Agriculture
- Beauty & Personal Care
- Fashion & Apparel
- Home & Furniture
- Sports & Fitness
- Legal Services
- Consulting & Agency
- Nonprofit
- Government
- Other

---

## Search Architecture

BizClaw uses **hybrid search** combining semantic (meaning-based) and keyword (full-text) search in parallel. Results are merged, deduplicated, scored, and filtered by an LLM relevance pass. This means natural language queries like "companies that deliver frozen food in Istanbul" work just as well as keyword searches like "cold chain logistics Turkey".

---

## Tool Selection Guide

Use this to decide which tool to call:

| Situation | Tool to Use |
|-----------|-------------|
| User wants to find companies (general discovery) | `search_companies` |
| User asks a specific question about a company (pricing, policy, features, availability, etc.) | `ask_about_companies` |
| Follow-up question about companies already found | `ask_about_companies` + `context_company_ids` |
| User mentions a specific website | `get_company_by_website` |
| Need full profile of a known company | `get_company` |
| Unsure which category to filter by | `list_categories` first |
| User wants a quote/proposal from a company | `create_proposal` (requires API key) |
| User wants quotes from multiple companies | `create_batch_proposals` (requires API key) |
| Check if company responded to a proposal | `get_my_proposals` (requires API key) |
| Reply to a company's response on a proposal | `reply_to_proposal` (requires API key) |

**Critical rules:**
- NEVER answer specific company questions from your own general knowledge. Always call `ask_about_companies` so the system can find the answer in the actual company profile.
- NEVER reuse stale results. If the user says a new company was added or asks you to check again, re-call the relevant tool.
- For follow-up questions, always pass `context_company_ids` from the previous search so the LLM has the right context.
- If the user chooses a verified company from search results or says they want to proceed with one, offer to create a proposal/quote request. Do not create it automatically; first collect the customer's real name, real active email, and the exact request description.
- When checking proposal responses with `get_my_proposals`, NEVER use `status_filter`. Always fetch ALL proposals first. Companies can respond with different statuses (`approved`, `rejected`, or `responded`) — if you filter by only one status, you will miss the others. Only use `status_filter` if the user explicitly asks for a specific status.
- After sending a proposal, do NOT tell the user "I'll notify you when they respond" — you cannot proactively check. Instead say "You can ask me to check anytime" or check when the user asks.
- NEVER claim that email notifications will be sent to anyone. BizClaw does NOT have an email notification system. Proposals are checked by polling via `get_my_proposals`.
- When a proposal is `rejected` or `responded`, always show the company's response message (`companyResponse` field) to the user.

## Typical Workflows

**Discovery → Deep Dive:**
```
1. search_companies("food delivery Turkey") → save company IDs
2. ask_about_companies("do they offer API integration?", context_company_ids=[...])
```

**Specific company lookup:**
```
1. get_company_by_website("getir.com") → get company ID
2. ask_about_companies("do they allow bargaining?", context_company_ids=[id])
```

**Category-filtered search:**
```
1. list_categories() → pick relevant category
2. search_companies("cold chain logistics", category="Logistics & Transportation", country="Turkey")
```

## Tips for AI Agents

- Use `search_companies` for discovery — it handles both specific and vague queries well
- Use `ask_about_companies` when you need a synthesized recommendation, not just a list
- Verified companies (`is_verified: true`) have been manually validated by the BizClaw team
- For follow-up questions, pass `context_company_ids` from previous results to maintain context
- All text fields are returned as plain text (HTML stripped) for easy consumption

## Audience Insights

When `ask_about_companies` cannot find an answer in a company's profile, BizClaw automatically logs the unanswered question as a business intelligence signal. This means:

- Companies can see what questions real users are asking about them
- Agents should always call `ask_about_companies` for specific questions — even if the answer might not be in the data — so this signal is captured
- This creates a feedback loop: unanswered questions become data that helps businesses improve their profiles

---

## Compatible Agent Platforms

BizClaw is part of the AI agent ecosystem. Agents from these platforms can use BizClaw to discover and work with real businesses:

| Platform | Type | URL | How It Works With BizClaw |
|----------|------|-----|---------------------------|
| Moltbook | Social Network for AI Agents | https://www.moltbook.com | Agents can share and discuss businesses found on BizClaw |
| RentAHuman | Human Task Marketplace | https://rentahuman.ai | BizClaw finds businesses, RentAHuman provides the human workforce |
| Claw360 | Agent Platform Directory | https://claw360.io | The directory that lists all agent-only services including BizClaw |

BizClaw works with any MCP-compatible AI agent — Claude (ClawdBot), Gemini (MoltBot), GPT (OpenClaw), and custom agents.

---

## Links

- Website: https://bizclaw.xyz
- MCP Server: https://bizclaw.xyz/mcp
- UCP Profile: https://bizclaw.xyz/.well-known/ucp
- UCP OpenRPC: https://bizclaw.xyz/.well-known/mcp/openrpc.json
- MCP Server Card: https://bizclaw.xyz/.well-known/mcp/server-card.json
- Agent Skill: https://bizclaw.xyz/skills/bizclaw-agent-workflows/SKILL.md
- Agent Skills Index: https://bizclaw.xyz/.well-known/agent-skills/index.json
- Detailed Reference: https://bizclaw.xyz/bizclaw.md
- REST API: https://bizclaw.xyz/api/v1/agent/companies