> For the complete documentation index, see [llms.txt](https://mcp.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp.conserver.io/api-reference/index.md).

# Overview

Complete API documentation for the vCon MCP Server.

## Overview

The vCon MCP Server provides a comprehensive API for managing virtual conversations through the Model Context Protocol (MCP). All interfaces are fully compliant with [IETF vCon Core](https://datatracker.ietf.org/doc/html/draft-ietf-vcon-vcon-core-02) specification.

For new MCP clients, start with the redesigned contract surface: `vcon_capabilities`, `vcon_taxonomy`, `vcon_search`, `vcon_fetch`, and `describe_response_shape`. The older tools remain available for backward compatibility and specialized workflows.

***

## API Components

### 🌐 [REST API](/api-reference/rest-api.md)

Full HTTP REST API with parity to all MCP tools (30+ endpoints):

* **vCon CRUD** - Create, read, update, delete + batch ingest
* **Discovery + Filtered Reads** - Discover live categories, then read by attachment `purpose` or analysis `type`
* **Sub-resources** - Read or append analysis and attachments, append dialog
* **Tags** - Per-vCon tag management + tag discovery
* **Search** - Keyword, semantic, and hybrid search
* **Database** - Schema shape, stats, size, health monitoring
* **Analytics** - Growth, content, tag, and attachment analytics
* **Infrastructure** - Health, version, schema, examples

[View REST API Reference →](/api-reference/rest-api.md)

***

### 🛠️ [Tools](/api-reference/tools.md)

46 MCP tools for vCon operations:

* **Redesigned Contract Tools** - Discovery-first search, fetch, and aggregation with predictable envelopes
* **Core Operations** - Create, read, update, delete vCons
* **Component Management** - Add, update, and remove parties, dialog, analysis, attachments
* **Search & Query** - Keyword, semantic, and hybrid search
* **Tag Management** - Organize with key-value metadata
* **Database Tools** - Inspect and optimize database
* **Schema & Examples** - Get schemas and example vCons

[View Tools Reference →](/api-reference/tools.md)

***

### 🔗 [Resources](/api-reference/resources.md)

URI-based access to vCon data:

* `vcon://v1/discovery/attachments/purposes` - Discover live attachment purposes
* `vcon://v1/discovery/attachments/types` - Discover legacy attachment types
* `vcon://v1/discovery/analysis/types` - Discover live analysis types
* `vcon://v1/vcons/recent` - Get recent vCons
* `vcon://v1/vcons/recent/ids` - Lightweight ID lists
* `vcon://v1/vcons/ids` - Paginated ID browsing
* `vcon://v1/vcons/{uuid}` - Get specific vCon
* `vcon://v1/vcons/{uuid}/metadata` - Get metadata only
* `vcon://v1/vcons/{uuid}/attachments/purpose/{purpose}` - Read attachments by purpose
* `vcon://v1/vcons/{uuid}/attachments/type/{type}` - Read attachments by legacy type
* `vcon://v1/vcons/{uuid}/analysis/type/{type}` - Read analysis by type

[View Resources Reference →](/api-reference/resources.md)

***

### 💬 [Prompts](/api-reference/prompts.md)

9 query template prompts:

* **find\_by\_exact\_tags** - Exact tag matching
* **find\_by\_semantic\_search** - AI-powered meaning search
* **find\_by\_keywords** - Keyword/phrase search
* **find\_recent\_by\_topic** - Recent conversations by topic
* **find\_by\_customer** - Search by party/customer
* **discover\_available\_tags** - Explore available tags
* **complex\_search** - Multi-criteria searches
* **find\_similar\_conversations** - Find similar vCons
* **help\_me\_search** - Query strategy guidance

[View Prompts Reference →](/api-reference/prompts.md)

***

### 📘 [Types](/api-reference/types.md)

TypeScript type definitions:

* **VCon** - Main conversation object
* **Party** - Conversation participants
* **Dialog** - Conversation segments
* **Analysis** - AI/ML analysis results
* **Attachment** - Additional files/data
* **Input/Output Types** - Tool parameters and responses

[View Types Reference →](/api-reference/types.md)

***

### 🗄️ [Database Schema](https://github.com/vcon-dev/vcon-mcp/tree/main/docs/api/schema.md)

PostgreSQL/Supabase schema:

* **Core Tables** - vcons, parties, dialog, analysis, attachments
* **Search Tables** - vcon\_embeddings, vcon\_tags\_mv
* **Privacy Tables** - privacy\_requests (GDPR/CCPA)
* **RPC Functions** - search\_vcons\_keyword, search\_vcons\_semantic, search\_vcons\_hybrid
* **Indexes** - Performance optimization

[View Schema Reference →](https://github.com/vcon-dev/vcon-mcp/tree/main/docs/api/schema.md)

***

## Quick Start Examples

### Create a vCon

```typescript
const result = await callTool("create_vcon", {
  vcon_data: {
    vcon: "0.4.0",
    subject: "Customer Support Call",
    parties: [
      {
        name: "Agent Smith",
        mailto: "smith@company.com"
      },
      {
        name: "John Doe",
        tel: "+1-555-1234"
      }
    ]
  }
});

console.log("Created vCon:", result.uuid);
```

### Search vCons

```typescript
// Discover search modes and include groups first
const capabilities = await callTool("vcon_capabilities", {});

// Unified keyword search
const results = await callTool("vcon_search", {
  mode: "keyword",
  query: "billing issue refund",
  filters: {
    tags: {
      department: "support",
      priority: "high"
    }
  },
  include: ["core", "summary", "dealer", "tags"],
  limit: 20
});
```

### Access via Resources

```typescript
// Get recent vCons
const recent = await readResource("vcon://v1/vcons/recent/10");

// Get specific vCon
const vcon = await readResource(
  "vcon://v1/vcons/123e4567-e89b-12d3-a456-426614174000"
);

// Discover live attachment purposes first
const purposes = await readResource("vcon://v1/discovery/attachments/purposes");

// Then read a specific category-backed view
const dealerInfo = await readResource(
  "vcon://v1/vcons/123e4567-e89b-12d3-a456-426614174000/attachments/purpose/dealer_info"
);

// List IDs for navigation
const ids = await readResource("vcon://v1/vcons/recent/ids/50");
```

### Use Query Prompts

```typescript
// Get query guidance
const prompt = await getPrompt("find_by_exact_tags", {
  tag_criteria: "angry customers",
  date_range: "June 2024"
});

// Follow the prompt's strategy to execute search
```

***

## Architecture

### Protocol Flow

```
┌──────────────────────────────────────────────────────────────┐
│                        Clients                               │
├─────────────────────────────────┬────────────────────────────┤
│   AI Assistants (MCP)           │   External Systems (REST)  │
│   (Claude Desktop, Custom)      │   (Integrations, Pipelines)│
└───────────────┬─────────────────┴──────────────┬─────────────┘
                │ MCP (stdio/HTTP)                │ HTTP/JSON
                │                                 │
┌───────────────▼─────────────────────────────────▼────────────┐
│                     vCon MCP Server                          │
│  ┌──────────────────────────┬───────────────────────────┐    │
│  │   MCP Handlers           │   REST API (30+ routes)   │    │
│  │  - Tools (30+)           │  - CRUD + sub-resources   │    │
│  │  - Resources             │  - Tags + tag discovery   │    │
│  │  - Prompts               │  - Search (3 modes)       │    │
│  │                          │  - Database + analytics   │    │
│  │                          │  - Health, schema, docs   │    │
│  └────────────┬─────────────┴────────────┬──────────────┘    │
│               │                          │                   │
│  ┌────────────▼──────────────────────────▼──────────────┐    │
│  │               VCon Service                           │    │
│  │  - Lifecycle hooks (beforeCreate, afterCreate, ...)  │    │
│  │  - Validation                                        │    │
│  │  - Metrics                                           │    │
│  └────────────────────────┬─────────────────────────────┘    │
│                           │                                  │
│  ┌────────────────────────▼─────────────────────────────┐    │
│  │               Plugin Manager                         │    │
│  │  - Privacy plugins                                   │    │
│  │  - Access control                                    │    │
│  │  - Custom extensions                                 │    │
│  └────────────────────────┬─────────────────────────────┘    │
│                           │                                  │
└───────────────────────────┼──────────────────────────────────┘
                            │ Supabase Client
                            │
                 ┌──────────▼───────────┐
                 │      PostgreSQL      │
                 │      (Supabase)      │
                 │                      │
                 │  - vCon Tables       │
                 │  - pgvector          │
                 │  - GIN/GiST Indexes  │
                 └──────────────────────┘
```

### Data Flow

1. **Client Request** - Client calls MCP tool/resource
2. **Validation** - Zod schema validation
3. **Database Query** - PostgreSQL operations
4. **Processing** - Business logic, search, embeddings
5. **Response** - Formatted JSON response

***

## API Capabilities

### Search Modes

| Mode         | Best For         | Performance      | Accuracy       |
| ------------ | ---------------- | ---------------- | -------------- |
| **Metadata** | Exact filters    | Fast (\~50ms)    | Exact match    |
| **Keyword**  | Specific words   | Medium (\~100ms) | High precision |
| **Semantic** | Concepts/meaning | Slower (\~200ms) | Contextual     |
| **Hybrid**   | Best of both     | Slower (\~300ms) | Balanced       |
| **Tag**      | Categories       | Fast (\~50ms)    | Exact match    |

### Operations

| Operation  | Tool | Resource | Prompt |
| ---------- | ---- | -------- | ------ |
| **Create** | ✅    | ❌        | ❌      |
| **Read**   | ✅    | ✅        | ❌      |
| **Update** | ✅    | ❌        | ❌      |
| **Delete** | ✅    | ❌        | ❌      |
| **Search** | ✅    | ❌        | ✅      |
| **Browse** | ❌    | ✅        | ❌      |

***

## Standards Compliance

### vCon Specification

✅ **Draft IETF vCon Core 00**

* All required fields supported
* Optional extensions available
* Group references implemented
* Redaction/appending supported

### MCP Protocol

✅ **Model Context Protocol 1.0**

* Tools interface
* Resources interface
* Prompts interface
* Standard error handling

### Database

✅ **PostgreSQL 15+**

* Full SQL compliance
* JSONB support
* Array operations
* GIN/GiST/HNSW indexes

✅ **pgvector Extension**

* Vector similarity search
* Cosine distance
* HNSW indexing

***

## Authentication & Security

### Supabase Authentication

The server uses Supabase authentication:

```typescript
// Environment variables required
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key-here
```

### Row Level Security (RLS)

Optional RLS policies can be enabled:

```sql
-- Enable RLS on vcons table
ALTER TABLE vcons ENABLE ROW LEVEL SECURITY;

-- Example policy: Users can only see their own vCons
CREATE POLICY "Users can view own vCons"
  ON vcons FOR SELECT
  USING (auth.uid() = user_id);
```

### API Key Management

For production deployments:

1. Use service role key for server
2. Use anon key for clients
3. Implement RLS policies
4. Enable database audit logging

***

## Error Handling

All API responses include error information:

```typescript
interface ErrorResponse {
  success: false;
  error: string;
  details?: any;
}
```

### Common Error Codes

* `VALIDATION_ERROR` - Invalid input parameters
* `NOT_FOUND` - vCon or resource not found
* `DATABASE_ERROR` - Database operation failed
* `PERMISSION_DENIED` - Insufficient permissions

***

## Versioning

### API Version

Current: **1.2.0**

The API follows semantic versioning:

* **Major** - Breaking changes
* **Minor** - New features (backward compatible)
* **Patch** - Bug fixes

### vCon Version

Current: **0.4.0**

Follows IETF vCon specification versions.

***

## Next Steps

### For Users

1. [Getting Started Guide](https://github.com/vcon-dev/vcon-mcp/tree/main/guide/getting-started.md)
2. [Search Guide](https://github.com/vcon-dev/vcon-mcp/tree/main/guide/search.md)
3. [Tag Management Guide](https://github.com/vcon-dev/vcon-mcp/tree/main/guide/tags.md)
4. [Examples](https://github.com/vcon-dev/vcon-mcp/tree/main/examples/README.md)

### For Developers

1. [Development Guide](https://github.com/vcon-dev/vcon-mcp/tree/main/development/README.md)
2. [Plugin Development](https://github.com/vcon-dev/vcon-mcp/tree/main/development/plugins.md)
3. [Testing Guide](https://github.com/vcon-dev/vcon-mcp/tree/main/development/testing.md)
4. [Contributing](https://github.com/vcon-dev/vcon-mcp)

### Resources

* [IETF vCon Spec](https://datatracker.ietf.org/doc/html/draft-ietf-vcon-vcon-core-02)
* [Model Context Protocol](https://modelcontextprotocol.io/)
* [Supabase Docs](https://supabase.com/docs)
* [pgvector Docs](https://github.com/pgvector/pgvector)