### Export Sample Preview Usage Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Demonstrates how to call the export_sample_preview tool with specific parameters and shows an example of the expected response format.

```typescript
Tool Call:
export_sample_preview({
  session_id: "sess_abc123",
  table_name: "search_results_tech",
  limit: 3,
  format: "table"
})

Response:
{
  "session_id": "sess_abc123",
  "table_name": "search_results_tech",
  "total_rows": 1247,
  "columns": ["company_name", "domain", "tech_stack", "website_keywords", ...],
  "sample": [
    { ... },
    { ... },
    { ... }
  ]
}
```

--------------------------------

### Install Gemini CLI Extension

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/PROJECT_OVERVIEW.md

Command to install the Gemini CLI extension, enabling integration with Gemini CLI.

```bash
gemini extensions install
```

--------------------------------

### Complete Workflow Example: Discovery, Enrichment, and Export

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Demonstrates a multi-turn workflow involving data discovery, enrichment, and finally exporting the processed data to a CSV file. This example shows the sequence of tool calls and the expected response for the export operation.

```text
Turn 1: Discovery
Tool: search_companies({
  filters: { industry: "B2B SaaS", location: "New York" }
})
→ Found 1,247 results, cost: 247 credits

Turn 2: Enrichment
Tool: enrich_technographics({
  session_id: "sess_abc123",
  table_name: "search_results",
  fields: ["tech_stack", "website_keywords"]
})
→ Enriched sample shown, cost updated: 395 credits

Turn 3: Export
Tool: export_to_csv({
  session_id: "sess_abc123",
  table_name: "search_results_tech"
})

Response:
{
  "download_url": "https://vibeprospecting.explorium.ai/export/sess_abc123_20260619_abc123.csv?expires=1718898000",
  "filename": "companies_tech_20260619_abc123.csv",
  "rows_exported": 1247,
  "columns": [
    "company_name",
    "domain",
    "industry",
    "location",
    "employee_count",
    "revenue",
    "tech_stack",
    "website_keywords",
    "hosting_provider"
  ],
  "credits_charged": 395,
  "expiration": "2026-06-20T13:45:00Z",
  "file_size_estimate": "8.3 MB"
}

Assistant Output:
"✓ Export complete!

**[Click here to download - companies_tech_20260619_abc123.csv](https://vibeprospecting.explorium.ai/export/sess_abc123_20260619_abc123.csv?expires=1718898000)**

**Export Details:**
- Rows exported: 1,247 companies
- Columns: 9 (name, domain, industry, location, employees, revenue, tech stack, keywords, hosting)
- Credits charged: 395
- File size: 8.3 MB
- Download expires: June 20, 2026 at 1:45 PM UTC

Your CSV is ready. You can download it from the link above within 24 hours."
```

--------------------------------

### Track Growth Tool Call Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Demonstrates how to call the track_growth tool with specific parameters. This example shows a typical request for analyzing growth over the last 12 months from a 'search_results_firm' table.

```javascript
Tool Call:
track_growth({
  session_id: "sess_abc123",
  table_name: "search_results_firm",
  time_period: "last_12_months"
})
```

--------------------------------

### Install Vibe Prospecting MCP Extension for Gemini CLI

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/README.md

Install the Vibe Prospecting MCP extension directly from its GitHub repository for use with Gemini CLI. OAuth sign-in is handled automatically on first use.

```bash
gemini extensions install https://github.com/explorium-ai/vibeprospecting-mcp
```

--------------------------------

### Track Growth Assistant Output Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Shows an example of how the assistant might interpret and present the data from a track_growth response. This output summarizes key growth metrics and trends in a human-readable format.

```text
"Growth trends for 1,247 companies over the past 12 months:

**Headcount Growth:** 18% annually
**Revenue Growth:** 32% annually
**Funding Growth:** 45% annually

Quarterly momentum: Accelerating in Q3-Q4 2025 after a dip in Q2. 
The dataset shows strong hiring and revenue growth, with particularly 
robust funding activity (45% YoY increase in capital raised)."
```

--------------------------------

### MCP Client Integration Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/ARCHITECTURE.md

Demonstrates how clients integrate with the MCP service using the MCP SDK. Initializes the client and calls a tool, with automatic OAuth handling.

```javascript
// Claude Code, Gemini CLI, Codex, etc.
const client = new MCPClient({
  transport: "http",
  url: "https://vibeprospecting.explorium.ai/mcp"
});

// OAuth happens automatically on first tool call
const result = await client.callTool("search_companies", {...});
```

--------------------------------

### Get Technology Autocomplete Suggestions

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/SEARCH_AND_DISCOVERY.md

This snippet demonstrates how to fetch technology suggestions, for example, for 'React'.

```typescript
get_autocomplete({
  filter_type: "tech_stack",
  prefix: "React",
  limit: 5
})
```

--------------------------------

### Search Companies Tool Call Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/TOOLS_OVERVIEW.md

Demonstrates how to call the search_companies tool with specific filters for industry, location, and employee count.

```javascript
search_companies({
  filters: {
    industry: "B2B SaaS",
    location: "New York",
    employee_count_min: 50,
    employee_count_max: 200
  }
})
```

--------------------------------

### Multi-Enrichment Workflow Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ENRICHMENT_TOOLS.md

Demonstrates a sequence of operations involving discovery, multiple enrichments, and final export. Shows how results from one step feed into the next.

```plaintext
Turn 1: Discovery
discover_contacts({
  filters: { title: "VP Engineering", industry: "SaaS" }
})
→ 234 contacts found
→ cost: 46 credits

Turn 2: First Enrichment
enrich_firmographics({
  session_id: "sess_xyz",
  table_name: "contact_results",
  fields: ["funding_rounds", "annual_revenue", "c_suite"]
})
→ Shows company funding info alongside contacts
→ cost updated: 78 credits

Turn 3: Second Enrichment
enrich_contacts({
  session_id: "sess_xyz",
  table_name: "contact_results_firm",  // use updated table
  fields: ["linkedin_profile", "career_history", "buying_signal"]
})
→ Shows contacts' career paths and company signals
→ cost updated: 145 credits

Turn 4: Export
export_to_csv({
  session_id: "sess_xyz",
  table_name: "contact_results_firm_profile"
})
→ 234 contacts exported with all enrichments
→ 145 credits charged
```

--------------------------------

### Analyze Market - Industry Breakdown Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/TOOLS_OVERVIEW.md

Example of performing an industry breakdown analysis. Requires session ID, table name, and analysis type.

```json
{
  "session_id": "sess_abc123",
  "table_name": "search_results",
  "analysis_type": "industry_breakdown",
  "results": {
    "total_records": 1247,
    "breakdown": [
      {
        "category": "B2B SaaS",
        "count": 512,
        "percentage": 41,
        "average_employee_count": 185,
        "average_revenue": 12000000
      },
      {
        "category": "Enterprise SaaS",
        "count": 389,
        "percentage": 31,
        "average_employee_count": 450,
        "average_revenue": 45000000
      },
      ...
    ]
  }
}
```

--------------------------------

### Discover Contacts Tool Call Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/TOOLS_OVERVIEW.md

Shows how to use the discover_contacts tool to find contacts based on job title, industry, location, and seniority.

```javascript
discover_contacts({
  filters: {
    title: "VP Engineering",
    industry: "SaaS",
    location: "New York",
    seniority: "C-level"
  }
})
```

--------------------------------

### Rate Limit Response Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

This JSON object indicates a rate limit has been hit and provides guidance on when to retry.

```json
{
  "error": "rate_limited",
  "message": "Too many requests. Retry after 30 seconds.",
  "retry_after_seconds": 30
}
```

--------------------------------

### Start a Fresh Search to Resolve 'Session Not Found'

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

If you encounter a 'Session not found' error, it indicates the session has expired. Start a new search to create a fresh session.

```python
search_companies() # Creates new session
```

--------------------------------

### Session Data Structure Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/ARCHITECTURE.md

Illustrates the hierarchical structure of data tables within a single session, including query plans, search results, and enrichment details.

```text
Session: sess_xyz123
├── original_query_plan
│   ├── filters: { industry: "B2B SaaS", ... }
│   ├── executed: false
│   └── sample_data: [5 rows]
│
├── search_results (table)
│   ├── session_id: "sess_xyz123"
│   ├── columns: [name, domain, employees, location, ...]
│   ├── row_count: 1247 (total, not yet fetched)
│   └── stored: on backend database
│
├── enrichment_plan_1
│   ├── operation: "enrich_technographics"
│   ├── fields: [tech_stack, website_keywords]
│   ├── executed: false
│   └── sample_data: [5 rows with tech data]
│
└── enriched_results (table)
    ├── session_id: "sess_xyz123"
    ├── columns: [name, domain, employees, location, tech_stack, ...]
    ├── row_count: 1247
    └── stored: on backend database
```

--------------------------------

### Compute Statistics Tool Call and Response

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

This example demonstrates how to call the compute_statistics tool with specific metrics and shows a sample response containing aggregate statistics.

```typescript
compute_statistics({
  session_id: "sess_abc123",
  table_name: "search_results_firm",
  metrics: ["average_employee_count", "median_revenue", "employee_growth_rate"]
})
```

```json
{
  "session_id": "sess_abc123",
  "total_records": 1247,
  "statistics": {
    "average_employee_count": {
      "mean": 185,
      "median": 120,
      "p25": 45,
      "p75": 350,
      "p95": 890
    },
    "median_revenue": {
      "median": 8000000,
      "p25": 2000000,
      "p75": 25000000,
      "p95": 120000000
    },
    "employee_growth_rate": {
      "average_yoy": "28%",
      "fastest_growth": "150% YoY",
      "slowest_growth": "-5% YoY",
      "median": "18% YoY"
    }
  }
}
```

--------------------------------

### Multi-Step Enrichment Pipeline Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

This pattern demonstrates building a comprehensive dataset by sequentially applying multiple enrichment layers, from firmographics and technographics to contact discovery and further contact enrichment, culminating in an export.

```javascript
Turn 1: Base Discovery
search_companies({ industry: "EdTech" })
→ 523 companies found

Turn 2: Layer 1 - Firmographics
enrich_firmographics({ fields: ["funding_rounds", "revenue", "c_suite"] })
→ Added company financial/leadership data

Turn 3: Layer 2 - Technographics
enrich_technographics({ fields: ["tech_stack", "hosting_provider"] })
→ Added technology insights

Turn 4: Layer 3 - Contact Discovery
(Reuse table as filter) discover_contacts({ company_domain: ... })
→ Get decision-makers at these companies

Turn 5: Layer 4 - Enrich Contacts
enrich_contacts({ fields: ["linkedin_profile", "buying_signal"] })
→ Add profile and intent signals

Turn 6: Export
export_to_csv()
→ Comprehensive dataset with all enrichments
```

--------------------------------

### Multi-Turn Workflow: Discovery, Enrichment, and Export

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/SEARCH_AND_DISCOVERY.md

This example demonstrates a complete workflow involving three sequential steps: discovering contacts based on specific criteria, enriching the discovered contacts with technographic data, and finally exporting the enriched results to a CSV file. It highlights the use of session IDs for state management across turns.

```tool_code
Turn 1: Discovery
---------
User: "Find marketing leaders at B2B SaaS companies, 50-200 people, in New York"

Tool: discover_contacts({
  filters: {
    title: "Marketing Director",
    industry: "B2B SaaS",
    location: "New York",
    seniority: "VP/Director"
  }
})

→ Found 89 contacts
→ sample_id: sess_mkt_001
→ cost to export: 18 credits
```

```tool_code
Turn 2: Enrichment (Reuse session)
----------
User: "Add their company's technology stack to this list"

Tool: enrich_technographics({
  session_id: "sess_mkt_001",
  table_name: "contact_results",
  fields: ["tech_stack", "website_keywords"]
})

→ Enriched sample shows tech stacks
→ updated cost to export: 45 credits (added enrichment)
```

```tool_code
Turn 3: Export
------
User: "Export to CSV"

Tool: export_to_csv({
  session_id: "sess_mkt_001",
  table_name: "enriched_tech"
})

→ Full execution: 89 contacts × enrichment data
→ CSV generated with 45 credits charged
→ Download link provided
```

--------------------------------

### Track Growth Response Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Illustrates the structure of the response received after calling the track_growth function. This includes session details, total records, detailed trends per period, and aggregate growth rates.

```json
{
  "session_id": "sess_abc123",
  "time_period": "last_12_months",
  "total_records": 1247,
  "trends": [
    { "period": "Q1 2025", "metric_value": 1204, "average_growth": "12% QoQ", "accelerating": false },
    { "period": "Q2 2025", "metric_value": 1156, "average_growth": "-4% QoQ", "accelerating": false },
    { "period": "Q3 2025", "metric_value": 1189, "average_growth": "3% QoQ", "accelerating": true },
    { "period": "Q4 2025", "metric_value": 1247, "average_growth": "5% QoQ", "accelerating": true }
  ],
  "aggregate_growth": {
    "headcount_growth_rate": "18% annually",
    "revenue_growth_rate": "32% annually",
    "funding_growth_rate": "45% annually"
  }
}
```

--------------------------------

### Call enrich_firmographics Tool

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ENRICHMENT_TOOLS.md

Example of how to call the `enrich_firmographics` tool with specific fields to enrich a search results table. This demonstrates the request parameters and the expected response structure.

```typescript
enrich_firmographics({
  session_id: "sess_abc123",
  table_name: "search_results",
  fields: ["funding_rounds", "annual_revenue", "c_suite", "headcount_history"]
})
```

--------------------------------

### CSV Export Cost Calculation Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

Illustrates how the cost of exporting data to CSV is calculated based on the number of records and enrichment factor. Use this to estimate credit consumption before exporting.

```plaintext
Cost = (number of records) × (enrichment factor)

Example:
  1,247 companies × base cost = 247 credits
  1,247 companies × (base + 1 enrichment) = 395 credits
  1,247 companies × (base + 3 enrichments) = 520 credits
```

--------------------------------

### Vibe Prospecting Session State Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

Illustrates the independent state maintained within a Vibe Prospecting session, including authentication token, query plans, result tables, and credits. This state is managed implicitly by the server.

```text
Session: sess_abc123 (implicit, managed by server)
├── Authentication: OAuth token for your account
├── Query plans: Accumulated discovery & enrichment operations
├── Result tables: search_results, enriched_tech, etc.
└── Credits: Tracked per operation within session
```

--------------------------------

### Add Vibe Prospecting MCP to Claude Code

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/README.md

Install the Vibe Prospecting MCP connector for Claude Code with a single terminal command. The first prompt execution will open a browser for authentication.

```bash
claude mcp add --transport http vibe-prospecting https://vibeprospecting.explorium.ai/mcp
```

--------------------------------

### AI Assistant Tool Call Example

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

This JSON structure represents a typical tool call made by an AI assistant to the Vibe Prospecting API, specifying filters for company search.

```json
{
  "filters": {
    "industry": "B2B SaaS",
    "location": "New York",
    "employee_count_min": 50,
    "employee_count_max": 200
  }
}
```

--------------------------------

### Implement Custom MCP Client with HTTP Transport

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

Use this JavaScript snippet to implement a custom MCP client with an HTTP transport. Ensure you have the @modelcontextprotocol/sdk installed. This client connects to a remote MCP server and allows calling tools.

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport, HttpClientTransport } from "@modelcontextprotocol/sdk/client/transport.js";

// HTTP transport (recommended for remote server)
const transport = new HttpClientTransport({
  url: "https://vibeprospecting.explorium.ai/mcp"
});

const client = new Client({
  name: "my-app",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

await client.connect(transport);

// Now call tools
const result = await client.callTool("search_companies", {
  filters: { industry: "SaaS" }
});
```

--------------------------------

### Get Autocomplete Suggestions

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/TOOLS_OVERVIEW.md

Use `get_autocomplete` to get suggestions for filter values based on a prefix. Specify the `filter_type` to autocomplete.

```json
{
  "type": "object",
  "properties": {
    "filter_type": {
      "type": "string",
      "enum": ["industry", "title", "department", "location", "seniority", "tech_stack", "company_name"],
      "description": "Which filter to autocomplete"
    },
    "prefix": {
      "type": "string",
      "description": "Partial text to match"
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "description": "Max suggestions"
    }
  },
  "required": ["filter_type"]
}
```

```json
{
  "filter_type": "industry",
  "suggestions": [
    {
      "value": "B2B SaaS",
      "count": 12543,
      "description": "Business-to-business software as a service"
    },
    {
      "value": "B2C SaaS",
      "count": 8234
    },
    {
      "value": "SaaS Consulting",
      "count": 945
    },
    ...
  ]
}
```

```tool_code
get_autocomplete({
  filter_type: "industry",
  prefix: "SaaS"
})
```

--------------------------------

### Get Industry Autocomplete Suggestions

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/SEARCH_AND_DISCOVERY.md

Use this snippet to get a list of industry suggestions based on a prefix. It limits the results to 5.

```typescript
get_autocomplete({
  filter_type: "industry",
  prefix: "SaaS",
  limit: 5
})
```

--------------------------------

### Initialize and Connect Custom MCP Client

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

Demonstrates how to set up an HTTP transport and initialize a custom MCP client. This is useful for applications that need direct integration with MCP services beyond pre-built clients.

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { HttpClientTransport } from "@modelcontextprotocol/sdk/client/transport.js";

const transport = new HttpClientTransport({
  url: "https://vibeprospecting.explorium.ai/mcp"
});

const client = new Client({
  name: "my-app",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

await client.connect(transport);
```

--------------------------------

### Export Sample Preview

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/TOOLS_OVERVIEW.md

Retrieve raw sample data for inspection without initiating a full download. Specify the session ID, table name, and an optional limit for the number of rows.

```tool_code
export_sample_preview({
  session_id: "sess_abc123",
  table_name: "enriched_tech",
  limit: 5
})
```

--------------------------------

### Search and Discovery Tools

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/README.md

Tools for searching companies, discovering contacts, and getting autocomplete suggestions. These are fundamental for initial data gathering.

```APIDOC
## `search_companies`

### Description
Searches for companies based on specified criteria.

### Method
Not specified (assumed to be part of a JSON-RPC call)

### Endpoint
Not specified

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Schema details available in `types-and-schemas.md`)
- **filters** (object) - Required - Criteria for company search.
- **limit** (integer) - Optional - Maximum number of results.

### Request Example
```json
{
  "method": "search_companies",
  "params": {
    "filters": {
      "industry": "Technology",
      "location": "USA"
    },
    "limit": 10
  }
}
```

### Response
#### Success Response
- **companies** (array) - List of CompanyRecord objects.

#### Response Example
```json
{
  "result": {
    "companies": [
      {
        "name": "Example Corp",
        "domain": "example.com"
      }
    ]
  }
}
```

## `discover_contacts`

### Description
Discovers contacts based on company and other filters.

### Method
Not specified (assumed to be part of a JSON-RPC call)

### Endpoint
Not specified

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Schema details available in `types-and-schemas.md`)
- **filters** (object) - Required - Criteria for contact discovery.
- **limit** (integer) - Optional - Maximum number of results.

### Request Example
```json
{
  "method": "discover_contacts",
  "params": {
    "filters": {
      "company_id": "company-123",
      "job_title_contains": "Engineer"
    },
    "limit": 5
  }
}
```

### Response
#### Success Response
- **contacts** (array) - List of ContactRecord objects.

#### Response Example
```json
{
  "result": {
    "contacts": [
      {
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
      }
    ]
  }
}
```

## `get_autocomplete`

### Description
Provides suggestions for filter values to aid in searches.

### Method
Not specified (assumed to be part of a JSON-RPC call)

### Endpoint
Not specified

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Schema details available in `types-and-schemas.md`)
- **field** (string) - Required - The field for which to get suggestions.
- **query** (string) - Required - The partial input for suggestions.

### Request Example
```json
{
  "method": "get_autocomplete",
  "params": {
    "field": "industry",
    "query": "Tech"
  }
}
```

### Response
#### Success Response
- **suggestions** (array) - List of suggested values.

#### Response Example
```json
{
  "result": {
    "suggestions": ["Technology", "Tech Services"]
  }
}
```
```

--------------------------------

### Quick Company Discovery with search_companies()

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

Use this pattern for initial research, market analysis, or competitive intelligence to find and preview companies matching specific criteria.

```text
User: "Show me fintech companies in San Francisco with 20–100 employees"

Assistant uses: search_companies()
Arguments:
  - industry: "Fintech"
  - location: "San Francisco"
  - employee_count_min: 20
  - employee_count_max: 100

Result:
  - Found 287 companies
  - Shows sample of 5
  - Cost to export: 57 credits
```

--------------------------------

### Get Job Title Autocomplete Suggestions

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/SEARCH_AND_DISCOVERY.md

Use this snippet to retrieve job title suggestions when a user provides a partial input like 'engineer'.

```typescript
get_autocomplete({
  filter_type: "title",
  prefix: "engineer",
  limit: 10
})
```

--------------------------------

### Verify Claude CLI Connection

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

List all configured MCP connections to verify that Vibe Prospecting has been added successfully and is connected.

```bash
claude mcp list
# Output: vibe-prospecting: https://vibeprospecting.explorium.ai/mcp - ✓ Connected
```

--------------------------------

### Project File Structure

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/PROJECT_OVERVIEW.md

Illustrates the directory layout and key files within the vibeprospecting-mcp project.

```text
vibeprospecting-mcp/
├── server/
│   └── index.js                # MCP server entry point
├── package.json                # Node.js dependencies and metadata
├── README.md                   # User-facing installation and usage
├── gemini-context-prompt.md    # Gemini-specific agent instructions
├── gemini-extension.json       # Gemini CLI extension manifest
└── LICENSE                     # MIT license
```

--------------------------------

### Contact Discovery and Enrichment Pipeline

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

This multi-turn pattern is ideal for lead generation and sales outreach, starting with discovering contacts and progressively enriching them with firmographic and technographic data before exporting.

```text
Turn 1: Discover
User: "Get VP Marketing contacts at B2B SaaS companies in New York"

Assistant uses: discover_contacts()
Result: Found 156 VPs of Marketing, shows sample

Turn 2: Enrich
User: "Add their company funding and tech stack"

Assistant uses: enrich_firmographics() + enrich_technographics()
Result: Sample now shows company funding and tech data

Turn 3: Export
User: "Export to CSV"

Assistant uses: export_to_csv()
Result: 156 contacts with all enrichments, CSV download link
```

--------------------------------

### Verify Codex CLI Connection

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

List all configured MCP servers to verify the Vibe Prospecting connection and check its authentication method.

```bash
codex mcp list
# Look for: vibe-prospecting | ... | Auth: OAuth
```

--------------------------------

### export_sample_preview

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Retrieves raw sample data for a specified table within a session, allowing for inspection without generating a full CSV export. Supports limiting the number of rows and specifying the output format.

```APIDOC
## `export_sample_preview`

### Description
Get raw sample data for inspection without generating a full CSV export. Supports limiting the number of rows and specifying the output format.

### Method
MCP Tool Call

### Endpoint
`export_sample_preview(params: SampleRequest)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`SampleRequest` object:
- **session_id** (string) - Required - Session ID
- **table_name** (string) - Required - Table to preview
- **limit** (number) - Optional - Number of rows (max 100), defaults to 5
- **format** (string) - Optional - Response format: "json" or "table", defaults to "json"

### Request Example
```typescript
export_sample_preview({
  session_id: "sess_abc123",
  table_name: "search_results_tech",
  limit: 3,
  format: "table"
})
```

### Response
#### Success Response (`SampleResponse`)
- **session_id** (string) - Session ID
- **table_name** (string) - Table name
- **sample** (object[]) - Sample rows
- **total_rows** (number) - Total records in table
- **columns** (string[]) - Column names

#### Response Example
```json
{
  "session_id": "sess_abc123",
  "table_name": "search_results_tech",
  "total_rows": 1247,
  "columns": ["company_name", "domain", "tech_stack", "website_keywords", ...],
  "sample": [
    { ... },
    { ... },
    { ... }
  ]
}
```
```

--------------------------------

### Configure Vibe Prospecting MCP with mcp-remote for Codex CLI

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/README.md

Use this TOML configuration block for Codex CLI if native OAuth is not supported. It utilizes `mcp-remote` and opens a browser for sign-in on first use.

```toml
[mcp_servers.vibe-prospecting]
command = "npx"
args = ["-y", "mcp-remote", "https://vibeprospecting.explorium.ai/mcp"]

```

--------------------------------

### Per-Conversation Session Flow

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/README.md

Illustrates the step-by-step process of a conversation session, from initial search to final export, highlighting credit consumption at each stage.

```text
Per-Conversation Session Flow:
┌─────────────────────────────────────────┐
│ Turn 1: search_companies()              │
│ ✓ Creates session_id                    │
│ ✓ Returns 5 sample companies            │
│ ✓ Cost estimate: 247 credits            │
│ ✗ No charge yet                         │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│ Turn 2: enrich_technographics()         │
│ ✓ Reuses session_id                     │
│ ✓ Returns enriched sample               │
│ ✓ Cost estimate updated: 395 credits    │
│ ✗ No charge yet                         │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│ Turn 3: export_to_csv()                 │
│ ✓ Reuses session_id                     │
│ ✓ Generates CSV with all data           │
│ ✓ Returns download link                 │
│ ✓ Charges 395 credits (NOW!)            │
└─────────────────────────────────────────┘
```

--------------------------------

### Location Distribution Analysis

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Analyze the geographical distribution of search results, grouped by a specified field like 'state'. This example shows the tool call and a partial JSON response indicating counts and percentages per location.

```json
Tool Call:
analyze_market({
  session_id: "sess_abc123",
  table_name: "search_results",
  analysis_type: "location_distribution",
  group_by: "state"
})

Response:
{
  "results": {
    "New York": { "count": 342, "percentage": 27 },
    "California": { "count": 515, "percentage": 41 },
    "Massachusetts": { "count": 189, "percentage": 15 },
    ...
  }
}
```

--------------------------------

### Reusing Vibe Prospecting Sessions Across Turns

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

Demonstrates how Vibe Prospecting sessions are automatically reused across conversation turns. The AI assistant maintains context and implicitly passes session IDs, eliminating the need for manual management.

```text
Turn 1: search_companies() 
  → Creates session sess_abc123, stores search plan
  
Turn 2: enrich_technographics(session_id: "sess_abc123")
  → Reuses same session, appends enrichment to plan
  
Turn 3: export_to_csv(session_id: "sess_abc123")
  → Executes full plan on same session
```

--------------------------------

### Lazy Evaluation Cost Progression in Multi-Turn Workflow

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

Demonstrates the lazy evaluation model where discovery and enrichment operations return samples instantly without charge. Credits are only consumed when the full data is explicitly exported.

```text
Cost Progression in Multi-Turn Workflow:

Turn 1: search_companies()
  → Sample returned instantly (no charge)
  → Cost estimate: 247 credits to export full 1,247 companies

Turn 2: enrich_technographics()
  → Enriched sample returned instantly (no charge)
  → Cost estimate updated: 395 credits (enrichment added cost)

Turn 3: enrich_firmographics()
  → Further enriched sample returned instantly (no charge)
  → Cost estimate updated: 520 credits (multiple enrichments)

Turn 4: export_to_csv()
  → Full data processed (NOW charged)
  → 520 credits charged
```

--------------------------------

### Call a Tool with Custom MCP Client

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

Shows how to invoke a specific tool ('search_companies') using the connected MCP client. This snippet is essential for interacting with the MCP's functionalities, such as data retrieval and analysis.

```javascript
// Call a tool
const result = await client.callTool("search_companies", {
  filters: {
    industry: "SaaS",
    employee_count_min: 50
  },
  limit: 5
});

console.log(result.sample); // 5 sample companies
console.log(result.cost_estimate); // Export cost
```

--------------------------------

### Enable Vibe Prospecting Debug Logging

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

Set the VIBE_DEBUG environment variable to true to enable verbose logging for troubleshooting purposes.

```bash
export VIBE_DEBUG=true
# Run your MCP client
```

--------------------------------

### Find VPs at Tech Companies

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/SEARCH_AND_DISCOVERY.md

Use this snippet to find contacts with specific job titles, industries, and locations. The response includes contact details, buying signals, and cost estimates for exporting.

```json
User: "Get VP Engineering contacts at SaaS companies in New York"

Tool Call:
discover_contacts({
  filters: {
    title: "VP Engineering",
    industry: "SaaS",
    location: "New York",
    seniority: "VP/Director"
  }
})

Response:
{
  "session_id": "sess_ghi789jkl",
  "table_name": "contact_results",
  "total_rows": 342,
  "sample": [
    {
      "contact_id": "contact_12345",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@acme.com",
      "title": "VP Engineering",
      "department": "Engineering",
      "seniority": "VP/Director",
      "company_name": "Acme Corp",
      "company_domain": "acme.com",
      "company_id": "comp_001",
      "location": "New York, NY",
      "country": "USA",
      "linkedin_profile": "https://linkedin.com/in/janesmith",
      "buying_signal": "hiring engineers, expanding team",
      "verified_email": true
    },
    ...
  ],
  "cost_estimate": {
    "credits_required": 68,
    "estimated_time_seconds": 8
  }
}

Assistant Output:
"Found 342 VP Engineering contacts at SaaS companies in New York. 
Showing a sample of 5. Here are the top decision-makers ready to contact."

[Table with contact details]

"To export all 342 contacts with verified emails and buying signals, 
it will cost 68 credits and take about 8 seconds."
```

--------------------------------

### AI Assistant Behavior on Rate Limiting

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/INTEGRATION_GUIDE.md

Upon hitting rate limits (100 tool calls/5 min, 10 exports/24 hours), the tool fails with a 429 status and `retry_after_seconds`. The assistant informs the user, suggests waiting, and does not retry immediately.

```text
Limit: 100 tool calls per 5 minutes
Export limit: 10 exports per 24 hours

If rate limit hit:
  Tool fails with: 429 Rate Limited
  Response includes: retry_after_seconds
  
AI Assistant behavior:
  - Acknowledges the limit
  - Suggests waiting N seconds
  - Does NOT retry immediately
  - Allows user to pause and continue later
```

--------------------------------

### Turn 1: Company Discovery Response

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/ARCHITECTURE.md

This is the server response after the initial company discovery. It includes a session ID, total row count, a sample of discovered companies, and an estimated cost.

```json
{
  "session_id": "sess_xyz123",
  "total_rows": 1247,
  "sample": [
    { name: "Acme Corp", location: "NYC", employees: 150, ... },
    { name: "Bolt Inc", location: "NYC", employees: 89, ... },
    ...
  ],
  "cost_estimate": {
    "credits_required": 247,
    "estimated_time_seconds": 12
  }
}
```

--------------------------------

### Export Sample Preview Function Signature

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/ANALYSIS_AND_EXPORT.md

Defines the signature for the export_sample_preview function, including its parameters and return type. It also shows the interfaces for SampleRequest and SampleResponse.

```typescript
export_sample_preview(params: SampleRequest): Promise<SampleResponse>

interface SampleRequest {
  session_id: string
  table_name: string
  limit?: number
  format?: "json" | "table"
}

interface SampleResponse {
  session_id: string
  table_name: string
  sample: Record<string, any>[]
  total_rows: number
  columns: string[]
}
```

--------------------------------

### Search Companies by Tech Stack and Funding

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/api-reference/SEARCH_AND_DISCOVERY.md

Use this snippet to filter companies by specific technologies they use and their funding status. This is useful for identifying companies with particular technical capabilities or investment stages.

```json
User: "Companies using React and Node.js in the UK with Series B+ funding"

Tool Call:
search_companies({
  filters: {
    tech_stack: ["React", "Node.js"],
    country: "UK",
    funding_status: ["Series B", "Series C", "Series D", "Public"]
  }
})

Response:
{
  "session_id": "sess_def456uvi",
  "table_name": "search_results",
  "total_rows": 234,
  ...
}
```

--------------------------------

### Update to HTTP Transport for MCP

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/configuration.md

Use these commands to remove the deprecated local 'uvx' command and add the MCP client with HTTP transport.

```bash
claude mcp remove vibe-prospecting
claude mcp add --transport http vibe-prospecting https://vibeprospecting.explorium.ai/mcp
```

--------------------------------

### Turn 1: Company Discovery Tool Call

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/ARCHITECTURE.md

This snippet shows the tool call for the initial company discovery phase. It filters companies by industry, location, and employee count, with a sample limit.

```tool_call
search_companies({
  filters: {
    industry: "B2B SaaS",
    location: "New York",
    employee_count: { min: 50, max: 200 }
  },
  limit: 5  # sample limit
})
```

--------------------------------

### Add Vibe Prospecting MCP to Codex CLI

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/README.md

Integrate Vibe Prospecting MCP with the Codex CLI. This command automatically handles OAuth sign-in by opening a browser.

```bash
codex mcp add vibe-prospecting --url https://vibeprospecting.explorium.ai/mcp
```

--------------------------------

### Credit Sufficiency Check Logic

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/_autodocs/ARCHITECTURE.md

Describes the decision tree for checking user credit balance before executing tool calls, leading to either Normal Mode or Out-of-Credits Mode.

```text
User has sufficient credits?
  ├─ YES → Normal Mode (Default)
  │   └─ Provide full assistance, no credit reminder
  │
  └─ NO → Out-of-Credits Mode (403 Error)
      ├─ Deny tool execution
      ├─ Explain what was requested and its value
      ├─ Suggest partial export if available
      └─ Always end response with credit purchase reminder
         (https://www.vibeprospecting.ai/pricing)
```

--------------------------------

### List Connected MCP Services in Claude Code

Source: https://github.com/explorium-ai/vibeprospecting-mcp/blob/main/README.md

Verify the connection status of Vibe Prospecting and other MCP services within Claude Code. This command lists all added MCP services and their connection status.

```bash
claude mcp list
# vibe-prospecting: https://vibeprospecting.explorium.ai/mcp - ✓ Connected
```