Skip to main content

​
Overview

Mindset AI enables customers to host their own RAG (Retrieval-Augmented Generation) systems as MCP servers. This is particularly important for cases where clients have requirements not to let their intellectual property reside in external systems like Mindset AI’s infrastructure. RAG MCP servers are registered like other client MCP servers in the Mindset AI system, with a special server type designation indicating they provide RAG capabilities. The Model Context Protocol (MCP) is a standardized way to make tools and capabilities available to AI agents and systems. By implementing your RAG system as an MCP server, you’re creating a standard interface that Mindset AI’s agents can seamlessly interact with, just as they would with any other tool or service.

​
Benefits of Implementing Your Own RAG MCP Server

  • Control over storage: Your complete document corpus remains in your infrastructure; only relevant segments are shared per query
  • Custom embedding models: Use your preferred embedding models and similarity algorithms optimized for your domain
  • Existing infrastructure: Leverage your current vector databases, search systems, and document processing pipelines
  • Access control: Apply your own security policies and user permissions at the source
  • Performance optimization: Tune retrieval and reranking specifically for your use cases and data
Important: RAG MCP servers must expose the rag_search tool. Any other tools exposed by your RAG MCP server will be ignored at this time.

​
Required Tool Implementation

RAG MCP servers must expose at least the following tools: Tool Name: rag_search (mandatory - exact name required) Tool Description: Searches the knowledge base for relevant information using semantic search Tool Parameters: 
{
  "search_phrases": {
    "type": "array",
    "items": { "type": "string" },
    "description": "1-5 search phrases for semantic retrieval",
    "minItems": 1,
    "maxItems": 5
  }
}

​
Request Format

The Mindset AI agent will send requests to the RAG MCP server using the standard MCP protocol: 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "rag_search",
    "arguments": {
      "search_phrases": [
        "key features?", 
        "Product X capabilities and specifications",
        "How does product X compare to competitors?",
        "Product X technical documentation",
        "Benefits and limitations of product X"
      ]
    }
  },
  "id": "request-123"
}

**Headers included with this request**:

x-user-id: user@example.com
x-session-tags: ["department:sales", "region:north", "Q4-2024", "premium_access"]
Authorization: Bearer YOUR_API_KEY

​
Key Points

Search Phrases: The Mindset AI agent generates 1-5 diverse search phrases:
  • search_phrases[0] always contains the user’s exact original input, unmodified
  • Additional phrases (if present) contain interpreted versions of the user’s query, incorporating conversational context at various levels of detail
  • The client’s RAG system should embed all phrases using their own embedding algorithm and perform retrieval/reranking
Headers Provided by Mindset AI (all lowercase):
  • x-user-id: Contains the exact user identifier (externalUserId) provided during session registration via AgentSessions API
  • x-session-tags: Contains the exact JSON array of tags provided when creating the agent session via the AgentSessions API. These are arbitrary strings that clients define for their own filtering/segmentation needs (e.g., “department:sales”, “SALES”, “region:north”, “Q4-2024”). Your RAG server can parse this JSON array and use these tags to filter search results according to your business logic.
  • authorization: Your API key (provided during registration) will be included as: Bearer YOUR_API_KEY
Note on Session Tags: These tags are completely defined by you when creating an agent session via the AgentSessions API. You can use any string format that makes sense for your organization - key-value pairs like “department:sales”, simple strings like “SALES”, document categories, time periods, access levels, or any other segmentation strategy. These tags will be sent in the x-session-tags header as a JSON array exactly as provided, allowing you to filter your RAG search according to your business logic. If you don’t need filtering, you can provide an empty array or omit tags when creating the session.

​
Implementing Access Control

Your RAG server should use the x-user-id and x-session-tags headers to filter search results according to your business logic. For example, you might:
  • Restrict results based on user’s department or role (from session tags)
  • Apply document-level permissions tied to the user ID
  • Filter by time periods or access levels indicated in tags
  • Combine multiple criteria for fine-grained access control
  • Use tags for A/B testing or feature flags to control which document sets are searchable

​
Using Search Phrases

You’ll receive 1-5 phrases with specific structure:
  • search_phrases[0]: The user’s exact original query (unmodified)
  • Additional phrases (if present): Context-aware interpretations with varying specificity
We recommend a parallel approach for performance:
  • Embed all phrases using your embedding model (in parallel)
  • Search with each phrase independently (in parallel)
  • Combine and deduplicate results
  • Apply your reranking strategy to the combined set
  • Return the top-N most relevant segments
Note: Parallel processing is important for maintaining good response times.

​
Response Format

The RAG MCP server must return results in the following format: 
{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "segments": [
      {
        "segment_uid": "unique-segment-id-123",
        "source_file_name": "product_manual.pdf",
        "source_file_type": "pdf",
        "headline": "Product X Advanced Features",
        "segment_summary": "This section covers advanced features including multi-core processing, GPU acceleration, and AI-powered workflows.",
        "raw_text": "The actual text content from the document segment...",
        "source_url": "https://docs.example.com/product_manual.pdf"
      },
      {
        "segment_uid": "unique-segment-id-456",
        "source_file_name": "technical_specs.docx",
        "source_file_type": "docx",
        "headline": "Product X Technical Specifications",
        "segment_summary": "Complete technical requirements and performance benchmarks for deployment.",
        "raw_text": "Technical specifications: CPU requirements...",
        "source_url": "https://docs.example.com/specs.docx"
      }
    ]
  },
  "id": "request-123"
}

​
Required Fields for Each Segment

  • segment_uid: Unique identifier for the segment (required)
  • source_file_name: Name of the source document (required)
  • source_file_type: File type/extension (required)
  • raw_text: The actual text content to be used by the LLM (required)

​
Optional Fields

  • headline: A brief (up to 10 words) summary of the segment text. Used for citations and source card titles. Fallback behavior: If omitted, Mindset AI will attempt to extract the first sentence from raw_text using basic punctuation rules. For best results with technical content, structured data, or multi-language text, we recommend providing this field.
  • segment_summary: A longer description of the segment content (1-3 sentences). Used in source card previews and citation pop-ups to give users more context. Fallback behavior: If omitted, Mindset AI will attempt to extract the second and third sentences from raw_text using basic punctuation rules. For best results with technical content, structured data, or multi-language text, we recommend providing this field.
  • source_url: URL to access the source document. This is the sole mechanism for users to view original sources when they click on citations or source cards in the agent output. While optional, providing this field enables users to verify and explore the full context of cited information. For audio/video content, consider deep-linking to the specific timestamp where the segment begins. Assuming that the user is already logged in to the host site, this URL can be a link to a suitable host page for the content - allowing the host site to seamlessly identify and validate the user’s access to the content and use all the existing content player or viewer UI (with all the associated functionality that comes with that). If that is not possible then more restricted URLs containing their own keys or time limited signed access could be used.
Note on Optional Fields: These fields give you control over how your content appears in the Mindset AI UI. You can choose to generate headline and segment_summary yourself (for better quality and domain-specific formatting), or omit them and let Mindset AI extract them automatically from raw_text. The automatic extraction is a best-effort approach - generating these fields yourself will typically provide better results, especially for technical content, structured data, or non-prose text. Response Size: We recommend returning 5-10 of your most relevant segments. Maximum 20 segments.

​
Error Handling

For errors, return standard JSON-RPC error format with appropriate error codes: 
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "RAG search failed: Database connection timeout"
  },
  "id": "request-123"
}
Common JSON-RPC error codes:
  • -32700: Parse error (invalid JSON) - like HTTP 400
  • -32600: Invalid request - like HTTP 400
  • -32601: Method not found - like HTTP 404 but for methods
  • -32602: Invalid params - like HTTP 400
  • -32603: Internal error - like HTTP 500
  • -32000 to -32099: Server-defined errors (your custom business logic)
For successful queries with no results, return an empty segments array: 
{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "segments": []
  },
  "id": "request-123"
}

​
Testing Your RAG MCP Server

You can test your RAG MCP server implementation using curl or any HTTP client. Here’s an example request that mimics how Mindset AI will call your server: 
curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -H "x-user-id: user@example.com" \
  -H "x-human-uid: human_123456789" \
  -H "x-session-tags: [\"department:sales\",\"premium_access\"]" \
  -d '{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "rag_search",
    "arguments": {
      "search_phrases": [
        "product features",
        "Product X capabilities and specifications",
        "How does product X compare to competitors?"
      ]
    }
  },
  "id": "request-123"
}'
Expected Response: 
{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "segments": [
      {
        "segment_uid": "unique-segment-id-123",
        "source_file_name": "product_manual.pdf",
        "source_file_type": "pdf",
        "headline": "Product X Advanced Features",
        "segment_summary": "This section covers advanced features including multi-core processing and GPU acceleration.",
        "raw_text": "The actual text content from the document segment...",
        "source_url": "https://docs.example.com/product_manual.pdf"
      }
    ]
  },
  "id": "request-123"
}

​
Upcoming Optional Tool: verify_document_access

​
Overview

This optional tool will address a key limitation with source document access: URLs to source documents may become stale over time due to expired authentication tokens, changed permissions, or document reorganization.

​
The Problem

When users click on source cards or citations in conversation threads (both current and historical), the external URLs may fail due to:
  • Expired tokens: URLs with embedded authentication tokens (e.g., ?token=abc123&expires=…) will fail when tokens expire
  • Permission changes: If access to a document is revoked, URLs will return 403 Forbidden errors
  • Document moves: If documents are reorganized, URLs pointing to old paths will return 404 Not Found errors
  • Session-based access: URLs that rely on active user sessions may fail when reopened later
This creates a poor user experience - users click on source cards or citations and encounter broken links or access denied errors.

​
The Solution

The verify_document_access tool will allow Mindset AI to verify that a user still has access to a document and optionally receive a refreshed URL for the document. When Called: This tool will be invoked every time a user clicks on a source card or citation in any conversation (current or historical). Mindset AI takes no chances when it comes to verifying access permissions - all clicks will trigger real-time verification. Tool Purpose:
  • Primary: Verify that the user currently has permission to access the document
  • Secondary: Optionally provide a refreshed URL with new authentication tokens/credentials

​
Tool Specification

Tool Name: verify_document_access Tool Description: Will verify user access to a document and optionally provide a refreshed URL with current credentials 
**Tool Parameters**:
{
  "segment_uid": {
    "type": "string",
    "description": "The unique segment identifier originally provided by your RAG server"
  }
}
Headers Provided by Mindset AI (same as rag_search):
  • x-user-id: Current user identifier (may differ from original query if shared)
  • x-session-tags: Current session tags (may differ from original session)
  • x-human-uid: Mindset AI internal user identifier
  • authorization: Your API key as Bearer YOUR_API_KEY
Note: The headers will contain current user context, not the original context from when the segment was first retrieved. This will allow you to verify that the current user agent session has access to the document. Expected Response: 
{
  "jsonrpc": "2.0",
  "result": {
    "has_access": true,
    "refreshed_url": "https://docs.example.com/product_manual.pdf?token=new_token_xyz&expires=...",
    "access_level": "view",
    "error": null
  },
  "id": "request-123"
}
Response Fields:
  • has_access (boolean, required): Whether the current user can access this document
  • refreshed_url (string, optional): New URL with fresh credentials. If omitted, the original URL will be reused.
  • access_level (string, optional): User’s permission level (e.g., “view”, “edit”, “admin”)
  • error (string, optional): Human-readable error message if access is denied
Access Denied Response: 
{
  "jsonrpc": "2.0",
  "result": {
    "has_access": false,
    "refreshed_url": null,
    "error": "Document has been deleted"
  },
  "id": "request-123"
}

​
Benefits of Implementation

For Users:
  • ✅ Source links will continue to work indefinitely across all conversations
  • ✅ Real-time permission checks will prevent access to documents they no longer have rights to
  • ✅ Seamless experience when clicking on sources or citations at any time
For Your System:
  • ✅ Full control over access verification logic
  • ✅ Generate fresh tokens on-demand rather than storing long-lived credentials
  • ✅ Audit trail of all document access attempts from Mindset AI conversations
  • ✅ Opportunity to handle document moves/renames gracefully

​
Implementation Considerations

  • Performance: This tool will be called every time users click on sources or citations, so response time will be critical
  • Caching: Consider caching verification results briefly (e.g., 5 minutes) to reduce load from repeated clicks
  • Graceful Degradation: If this tool is not implemented, Mindset AI will use the original URL (which may be stale)
  • Security: Use the current user context from headers to validate access, not cached permissions

​
Timeline

This tool specification will be finalized based on client feedback. Implementation will be optional - your RAG MCP server will function without it, but users may encounter stale URLs or permission issues when clicking on sources.
⌘I