MCP Overview

The Model Context Protocol (MCP) lets AI agents access your RAG system as standard tools. GuidedMind implements MCP over SSE (Server-Sent Events) transport.

Architecture

Connection Endpoints

Connecting

Step 1: Open SSE Connection

curl -N "https://api.guidedmind.ai/api/v1/mcp/sse?api_key=rk_your_key_here"

Response:

event: endpoint
data: /mcp/messages?session_id=uuid-here

Step 2: Send JSON-RPC Messages

curl -X POST "https://api.guidedmind.ai/api/v1/mcp/messages?session_id=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

JSON-RPC Format

All messages follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "rag_search",
    "arguments": {
      "query": "What is RAG?"
    }
  }
}

Available Tools

See MCP Per Tool for detailed parameter documentation.

Enhanced Search

rag_search returns richer results to help agents reason about relevance and cite sources:

• score_type — the semantics of each result's score: cosine_similarity for dense search, or a fusion label (e.g. rrf_fusion) for hybrid search. Hybrid scores are rank/fusion values, not probabilities.
• component_scores — for hybrid results, the dense and BM25 inputs to the fusion (e.g. {"dense": 0.82, "bm25": 12.4}).
• rerank_method — the project's hybrid rerank method (top-level field).
• document_url — a clickable link to each result's document in the web app.
• metadata_filter — restrict the search to documents whose stored metadata matches every key/value (e.g. {"type": "skill"}).
• include_graph / render_graph_image — optionally return the supporting knowledge-graph subgraph, rendered as a PNG image (MCP image content) alongside the JSON results.

Assistant Deep Links

For knowledge-graph changes or exploration, the server's MCP instructions point the agent at a deep link that opens the web app with the AI assistant pre-filled:

{FRONTEND_URL}/dashboard/rag-builder/{project_id}?assistant=open&message=<request>

The base URL is taken from the FRONTEND_URL environment variable (the same one the auth callback uses), so these links (and the per-result document_url / project_url links) always point at the same web app as the rest of your deployment.

Authentication

Pass your API key via the X-API-Key header on the SSE connection:

curl -N -H "X-API-Key: rk_your_key_here" "https://api.guidedmind.ai/mcp/sse"

The api_key query parameter is also accepted:

/mcp/sse?api_key=rk_your_key_here

The session ID from the endpoint event is then used for all subsequent message requests.

Error Handling

Errors are returned as JSON-RPC error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Valid Methods