# 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)

35 MCP tools for vCon operations:

* **Redesigned Contract Tools** - Discovery-first search and fetch with predictable envelopes
* **Core Operations** - Create, read, update, delete vCons
* **Component Management** - Add 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/blob/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/blob/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/blob/main/guide/getting-started.md)
2. [Search Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/guide/search.md)
3. [Tag Management Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/guide/tags.md)
4. [Examples](https://github.com/vcon-dev/vcon-mcp/blob/main/examples/README.md)

### For Developers

1. [Development Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/development/README.md)
2. [Plugin Development](https://github.com/vcon-dev/vcon-mcp/blob/main/development/plugins.md)
3. [Testing Guide](https://github.com/vcon-dev/vcon-mcp/blob/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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mcp.conserver.io/api-reference/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.