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

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 →

---

🛠️ Tools

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 →

---

🔗 Resources

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 →

---

💬 Prompts

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 →

---

📘 Types

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 →

---

🗄️ Database Schema

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 →

---

Quick Start Examples

Create a vCon

const result = await callTool("create_vcon", {
  vcon_data: {
    vcon: "0.4.0",
    subject: "Customer Support Call",
    parties: [
      {
        name: "Agent Smith",
        mailto: "[e-mail]"
      },
      {
        name: "John Doe",
        tel: "[phone]"
      }
    ]
  }
});

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

Search vCons

// 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

// 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

// 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:

// 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:

-- 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:

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

2. Search Guide

3. Tag Management Guide

4. Examples

For Developers

1. Development Guide

2. Plugin Development

3. Testing Guide

4. Contributing

Resources

• IETF vCon Spec

• Model Context Protocol

• Supabase Docs

• pgvector Docs