# Basic Usage Learn how to use the vCon MCP Server with AI assistants and common workflows. ## Prerequisites Before starting, ensure you have: * ✅ Completed [Installation](/guide/installation.md) * ✅ Configured Claude Desktop or another MCP client * ✅ Database migrations applied * ✅ Valid Supabase credentials in `.env` *** ## Quick Start ### Your First vCon Let's create your first vCon using Claude Desktop: **1. Ask Claude:** ``` Create a vCon for a customer support call between Alice (agent) and Bob (customer) discussing a refund request. ``` **Claude will:** * Use the `create_vcon` tool * Create parties for Alice and Bob * Set subject to describe the call * Return the vCon UUID **2. View the vCon:** ``` Show me the vCon you just created ``` **3. Add a transcript:** ``` Add a text dialog to this vCon: Bob: "Hi, I'd like to request a refund for order #12345" Alice: "I'd be happy to help you with that refund request." ``` **4. Add analysis:** ``` Add sentiment analysis showing positive sentiment (0.8 score) from "SentimentAI" vendor ``` Congratulations! You've created a complete vCon with dialog and analysis. *** ## Core Operations ### Creating vCons #### Basic Creation ``` Create a vCon with subject "Team Meeting" and party "John Doe" with email john@example.com ``` #### Using Templates ``` Create a phone_call vCon between two people discussing product pricing ``` Available templates: * `phone_call` - Two-party phone conversation * `chat_conversation` - Multi-party text chat * `email_thread` - Email conversation * `video_meeting` - Video conference call * `custom` - Start from scratch #### With Multiple Parties ``` Create a vCon for a sales call with: - Sales rep: Alice (alice@company.com) - Customer: Bob (bob@customer.com) - Manager: Carol (carol@company.com) Subject: "Q4 Contract Negotiation" ``` *** ### Reading vCons #### Get by UUID ``` Get the vCon with UUID abc-123-def-456 ``` #### Get Recent vCons ``` Show me the 10 most recent vCons ``` Or use the `vcon://v1/vcons/recent` resource: ``` Read the vcon://v1/vcons/recent resource ``` #### Get Specific Fields ``` Show me just the parties from vCon abc-123 ``` Use resources: * `vcon://v1/vcons/{uuid}/parties` - Just parties * `vcon://v1/vcons/{uuid}/dialog` - Just dialog * `vcon://v1/vcons/{uuid}/analysis` - Just analysis * `vcon://v1/vcons/{uuid}/attachments` - Just attachments * `vcon://v1/vcons/{uuid}/metadata` - Just metadata * `vcon://v1/vcons/{uuid}/transcript` - Transcript analysis (derived) * `vcon://v1/vcons/{uuid}/summary` - Summary analysis (derived) * `vcon://v1/vcons/{uuid}/tags` - Tags as object (derived) *** ### Searching vCons #### Basic Search (Filtering) Search by subject, party name, or date: ``` Find vCons from last week about billing ``` ``` Find vCons where John Smith was a participant ``` ``` Search for vCons created between Jan 1 and Jan 31 with subject "support" ``` #### Keyword Search Full-text search across dialog and analysis: ``` Search for conversations mentioning "refund" or "return" ``` ``` Find vCons where someone said "technical issue" ``` #### Semantic Search AI-powered search by meaning (requires embeddings): ``` Find conversations where customers were frustrated with delivery ``` ``` Search for discussions about product features ``` #### Hybrid Search Combines keyword and semantic for best results: ``` Search for billing disputes using both exact matches and similar concepts ``` *** ### Adding Content #### Add Dialog Add conversation segments: ``` Add a recording dialog to vCon abc-123: - Type: recording - Start time: 2025-01-15T10:00:00Z - Duration: 300 seconds - URL: https://storage.example.com/call123.mp3 ``` ``` Add a text message: "Hi, thanks for calling support!" From party 0 at 10:00 AM ``` #### Add Analysis Add AI/ML analysis results: ``` Add transcript analysis to vCon abc-123: - Type: transcript - Vendor: OpenAI - Product: Whisper-1 - Body: "Full transcript text here..." - Dialog: 0 (references first dialog) ``` ``` Add sentiment analysis showing negative sentiment (-0.6) from vendor "SentimentAnalyzer" ``` #### Add Attachments Attach related files: ``` Add an attachment to vCon abc-123: - Type: application/pdf - Party: 1 - Body: base64-encoded PDF content ``` *** ### Updating vCons Update top-level vCon metadata: ``` Update vCon abc-123 with subject "Updated Subject Line" ``` ``` Add a "priority" extension with value "high" to vCon abc-123 ``` **Note:** To modify parties, dialog, or analysis, add new items. The vCon spec favors immutability. *** ### Tagging & Organization #### Add Tags ``` Tag vCon abc-123 as: - department: support - priority: high - customer_id: CUST-789 ``` #### Search by Tags ``` Find all vCons tagged as department:sales and priority:high ``` ``` Show me high priority support tickets from this week ``` #### View All Tags ``` Show me all unique tags in the database ``` #### Remove Tags ``` Remove the priority tag from vCon abc-123 ``` See [Tag Management Guide](/guide/tags.md) for complete tag documentation. *** ### Deleting vCons ``` Delete vCon abc-123 ``` **Warning:** This permanently deletes the vCon and all related data (parties, dialog, analysis, attachments). This action cannot be undone. *** ## Common Workflows ### Workflow 1: Customer Support Call **Step 1: Create vCon** ``` Create a support call vCon between agent Sarah and customer Mike about a billing issue ``` **Step 2: Add Recording** ``` Add a recording dialog: - URL: https://recordings.example.com/call-456.mp3 - Duration: 420 seconds - Start time: now ``` **Step 3: Add Transcript** ``` Add transcript analysis from OpenAI Whisper showing the conversation... ``` **Step 4: Add Sentiment** ``` Add sentiment analysis showing the customer was initially frustrated (-0.4) but ended satisfied (0.7) ``` **Step 5: Tag for Organization** ``` Tag this vCon: - department: support - issue_type: billing - resolution: resolved - customer_satisfaction: high ``` **Step 6: Search Later** ``` Find all resolved billing issues from this month where customer satisfaction was high ``` *** ### Workflow 2: Sales Call Analysis **Step 1: Create from Template** ``` Create a phone_call vCon for a sales discovery call with prospect Jane at Acme Corp ``` **Step 2: Add Transcript** ``` Add the call transcript as analysis... ``` **Step 3: Extract Action Items** ``` Add analysis of type "action_items" with extracted next steps ``` **Step 4: Generate Summary** ``` Add a summary analysis highlighting key discussion points and customer pain points ``` **Step 5: Tag** ``` Tag as: - sales_stage: discovery - industry: enterprise_software - deal_size: 50k - next_action: demo_scheduled ``` *** ### Workflow 3: Research Dataset **Step 1: Batch Create vCons** ``` Create 5 vCons for research interviews about user experience ``` **Step 2: Add Interview Transcripts** ``` For each vCon, add the transcript as a text dialog ``` **Step 3: Add Analysis** ``` Add theme analysis identifying common patterns ``` **Step 4: Search Across Dataset** ``` Search all research vCons for mentions of "usability issues" ``` **Step 5: Export Findings** ``` Get all vCons tagged as research:ux_study and show their analysis results ``` *** ## Using with Claude Desktop ### Example Conversations #### Natural Language Commands Claude understands natural language - you don't need precise syntax: ``` ❌ create_vcon(subject="test", parties=[...]) ✅ Create a vCon for a team meeting ✅ Make a new vCon about product development ✅ Set up a vCon for yesterday's client call ``` #### Complex Queries ``` Find all customer support vCons from last quarter where the sentiment was negative and the issue was about billing, then show me the most common complaints ``` Claude will: 1. Search vCons by date range 2. Filter for support + billing tags 3. Filter for negative sentiment 4. Analyze common themes 5. Present findings #### Multi-Step Operations ``` Create a vCon for a sales call, add the transcript from the file I shared, analyze the sentiment, extract action items, and tag it appropriately ``` Claude can chain multiple tool calls automatically. *** ## Tips & Best Practices ### Creating vCons ✅ **DO:** * Use descriptive subjects * Add all parties involved * Include timestamps when known * Use templates for common scenarios ❌ **DON'T:** * Create duplicate vCons * Leave subject empty unless truly unknown * Forget to specify party roles ### Adding Content ✅ **DO:** * Reference dialog indexes in analysis * Include vendor info for all analysis * Use appropriate encoding (none/json/base64url) * Add timestamps to dialog ❌ **DON'T:** * Store large files directly (use URLs instead) * Mix encoding types inconsistently * Forget to specify analysis type ### Searching ✅ **DO:** * Use semantic search for conceptual queries * Use keyword search for exact terms * Use hybrid search when uncertain * Add tags for better organization ❌ **DON'T:** * Search by vCon content without indexes * Expect instant results with semantic search (requires embeddings) * Over-complicate search queries ### Tagging ✅ **DO:** * Use consistent tag naming (e.g., `department:sales`) * Tag early and often * Use hierarchical tags (e.g., `issue:billing:refund`) * Document your tag schema ❌ **DON'T:** * Create one-off tag names * Use spaces in tag keys * Forget to remove outdated tags *** ## Understanding Resources Resources provide read-only access to vCon data: ### List Resources ``` What vCon resources are available? ``` ### Common Resources | Resource | Purpose | Example | | ------------------------------------ | ------------------------ | --------------------------- | | `vcon://v1/vcons/recent` | 10 most recent vCons | Full vCon objects | | `vcon://v1/vcons/recent/25` | Recent with custom limit | Max 100 | | `vcon://v1/vcons/{uuid}` | Specific vCon | Complete vCon | | `vcon://v1/vcons/{uuid}/metadata` | Just metadata | Without dialog/analysis | | `vcon://v1/vcons/{uuid}/parties` | Just parties | Array of parties | | `vcon://v1/vcons/{uuid}/dialog` | All dialog | Array of dialog objects | | `vcon://v1/vcons/{uuid}/analysis` | All analysis | Array of analysis objects | | `vcon://v1/vcons/{uuid}/attachments` | All attachments | Array of attachment objects | | `vcon://v1/vcons/{uuid}/transcript` | Transcript analysis | Filtered analysis array | | `vcon://v1/vcons/{uuid}/summary` | Summary analysis | Filtered analysis array | | `vcon://v1/vcons/{uuid}/tags` | Tags | Parsed tags object | ### Using Resources ``` Read vcon://v1/vcons/recent ``` ``` Read vcon://v1/vcons/abc-123-def/parties ``` Resources are faster than tools for simple reads. *** ## Understanding Prompts Prompts guide Claude in using the right search strategy: ### Available Prompts 1. **find\_by\_exact\_tags** - Precise tag matches 2. **find\_by\_semantic\_search** - Meaning-based search 3. **find\_by\_keywords** - Text search 4. **find\_recent\_by\_topic** - Recent vCons on topic 5. **find\_by\_customer** - Customer-specific vCons 6. **discover\_available\_tags** - Explore tag schema 7. **complex\_search** - Multi-criteria queries 8. **find\_similar\_conversations** - Similar to example 9. **help\_me\_search** - Search strategy help ### Using Prompts Claude automatically selects the right prompt, but you can request: ``` Use exact tag matching to find high-priority sales calls ``` ``` Help me search for what I'm looking for ``` See [Prompts Guide](/guide/prompts.md) for detailed documentation. *** ## Error Handling ### Common Errors #### "vCon not found" ``` ❌ Get vCon abc-123 Error: vCon with UUID abc-123 not found ``` **Solution:** Check the UUID is correct: ``` ✅ Show me recent vCons to find the correct UUID ``` #### "Invalid vCon data" ``` ❌ Create vCon without parties Error: vCon must have at least one party ``` **Solution:** Include required fields: ``` ✅ Create vCon with subject "Meeting" and party "Alice" ``` #### "Search returned no results" ``` ❌ Find vCons about "xyz" from 2020 No results found ``` **Solution:** Broaden search criteria: ``` ✅ Show me all vCons from 2020 first ``` *** ## Performance Tips ### For Large Datasets 1. **Use tags** for filtering before search 2. **Use date ranges** to limit scope 3. **Use resources** for simple reads 4. **Index dialog content** for keyword search 5. **Generate embeddings** for semantic search ### For Fast Queries 1. **Query by UUID** when known (fastest) 2. **Use resources** instead of tools for reads 3. **Limit results** to what you need 4. **Cache frequently accessed vCons** *** ## Database Tools The server includes database inspection tools: ### View Database Structure ``` Show me the database structure ``` Uses `get_database_shape` tool. ### View Performance Stats ``` What are the database performance stats? ``` Uses `get_database_stats` tool. ### Analyze Query Performance ``` Analyze this query: SELECT * FROM vcons WHERE subject LIKE '%test%' ``` Uses `analyze_query` tool. See [Database Tools Guide](/guide/database-tools.md) for details. *** ## Next Steps ### Learn More * [**Search Guide**](/guide/search.md) - Master all search capabilities * [**Tag Management**](/guide/tags.md) - Organize with tags * [**Prompts Guide**](/guide/prompts.md) - Understand prompts * [**API Reference**](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/api/README.md) - Complete tool documentation ### Advanced Usage * [**Plugin Development**](/development/plugins.md) - Extend functionality * [**Custom Tools**](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/development/custom-tools.md) - Add your own tools * [**Embeddings & Search**](/development/embeddings.md) - Set up semantic search ### Examples * [**Code Examples**](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/examples/README.md) - Real-world examples * [**Integration Patterns**](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/examples/README.md) - Integration guides *** ## Getting Help ### Quick Help in Claude ``` How do I create a vCon? ``` ``` What search tools are available? ``` ``` Help me search for frustrated customers ``` ### Documentation * [**Installation Guide**](/guide/installation.md) - Setup troubleshooting * [**API Reference**](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/api/README.md) - Tool parameters * [**Reference Docs**](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/reference/README.md) - Technical specifications ### Community * **GitHub Issues** - Bug reports * **GitHub Discussions** - Questions and ideas * **Discord** - Real-time chat (coming soon) *** ## Quick Reference ### Most Common Commands | Task | Example | | ------------ | ----------------------------------------- | | Create vCon | `Create a vCon for a support call` | | Get vCon | `Show me vCon abc-123` | | Search | `Find vCons about billing from last week` | | Add dialog | `Add a text dialog saying "Hello"` | | Add analysis | `Add sentiment analysis from OpenAI` | | Tag | `Tag this vCon as priority:high` | | Delete | `Delete vCon abc-123` | ### Key Concepts * **vCon** - Container for conversation data * **Party** - Participant in conversation * **Dialog** - Conversation segment (recording, text, etc.) * **Analysis** - AI/ML results (transcript, sentiment, etc.) * **Attachment** - Related files * **Tags** - Metadata for organization * **Resources** - Read-only data access * **Prompts** - Search strategy guidance *** **Ready to dive deeper?** Continue to [Search Guide](/guide/search.md) → --- # 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/guide/basic-usage.md?ask= ``` 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.