v0.5.0-mcp: Claude Desktop E2E (3 tools verified)

v0.5.0-mcp — MCP Server Verified in Claude Desktop

Release date: 2026-04-25

Summary

The trustrag-mcp package (v0.1.2, on PyPI) has been verified
end-to-end in Claude Desktop against the production Railway
backend. Three tools were invoked from a real Claude conversation and
returned trust-annotated answers, successful uploads, and audit
queries respectively.

This closes P5-GATE from the v0.2 design spec (Phase 5: MCP Server).

What changed in 0.1.2 (vs 0.1.1)

End-to-end testing in Claude Desktop surfaced a schema mismatch
between the deployed backend and the MCP wrapper — every
trustrag_query call failed with KeyError: 'trust_score' because
the backend had moved to a nested confidence.{score,level,breakdown}
shape while the wrapper still read the flat legacy keys.

Fixed in 0.1.2 (with legacy-shape fallback so older deploys still
work):

Field	Old (0.1.1)	New (0.1.2 reads)
query — trust score	trust_score	confidence.score
query — trust breakdown	trust_breakdown	confidence.breakdown
query — source document name	source.doc	source.document
audit entry — question	question	query
audit entry — trust score	trust_score	confidence_score
upload — chunk count	num_chunks	total_chunks

Audit endpoint params (max_trust_score, since_hours) were dropped
from the API call (the backend only supports limit/offset) and
filtering moved client-side in server.py with a widened fetch
window so the user-visible API didn't change.

10 tests pass (new shape, legacy fallback, audit client-side filter).

3 Tools Verified

Real I/O captured from a live MCP session against production
(2026-04-25). See docs/mcp-verification.md
for the full input/output log.

Tool	Purpose	Verified
trustrag_query	Ask the knowledge base; returns answer + trust score (4-factor breakdown) + citations	✅ Trust 72.8/100 returned with 5 sources
trustrag_upload_document	Upload a PDF path; backend chunks + embeds + stores in pgvector	✅ Returned document_id=b7106d01-…, 1 chunk indexed
trustrag_get_audit_log	Fetch recent audit entries (filter by max_trust_score)	✅ Returned 5 entries, all with trust < 90 (client-side filter working)

Claude Desktop screenshots will be added as visual companions when
captured. The verification doc is the canonical end-to-end proof.

Setup (for users)

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "trustrag": {
      "command": "uvx",
      "args": ["trustrag-mcp"],
      "env": {
        "TRUSTRAG_BACKEND_URL": "https://trustrag-production.up.railway.app"
      }
    }
  }
}

Windows location: %APPDATA%\Claude\claude_desktop_config.json
Mac location: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop, open a new conversation, and ask a question
that naturally invokes knowledge-base lookup. Example prompts:

"Use trustrag_query to answer: What OSHA rule covers fall protection at 6 feet?"
"Upload docs/sample.pdf via trustrag_upload_document then query it."

Architecture

• Transport: stdio (JSON-RPC over stdin/stdout)
• SDK: Anthropic's mcp Python library
• Tools: registered via @app.list_tools() in
  packages/trustrag-mcp/src/trustrag_mcp/server.py
• Dispatch: @app.call_tool() parses args, calls backend HTTP
  API, formats markdown response

See packages/trustrag-mcp/src/trustrag_mcp/server.py for the full
implementation (~150 lines).

Backend Latency Notes

The trustrag_query tool invokes the HTTP /api/query/ endpoint
which routes through the merged-prompt path (single Groq JSON call
returning answer + self-check). Post-WS1 optimizations bring
Claude Desktop tool-use under the 30s default timeout even for
cold-cache queries:

• Cache hit: ~300ms
• Cache miss (merged prompt, Llama 70B): 5-10s typical
• Cache miss (merged prompt, Llama 8B benchmark config): 3-6s

PyPI

• trustrag-mcp 0.1.2 —
  schema-aligned with current backend; published via
  pkg-mcp-v0.1.2 tag through the publish-pypi.yml workflow.

Install standalone:

pip install trustrag-mcp>=0.1.2          # persistent install
uvx trustrag-mcp                         # ephemeral (Claude Desktop uses this)

Existing 0.1.1 users: uvx --upgrade trustrag-mcp or restart Claude
Desktop after pip install -U trustrag-mcp.

Known Limitations

• MCP server currently assumes public-readable backend. For private
  deployments, set TRUSTRAG_BACKEND_URL to a host you control.
• No auth on /api/query/admin/clear-cache (portfolio scope). Do not
  expose this endpoint publicly if you care about cache poisoning.
• Tool output truncates sources to first 300 chars per chunk — large
  chunks are summarized.