Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vrin.cloud/llms.txt

Use this file to discover all available pages before exploring further.

The Vrin MCP server exposes two tools that work as a pair: one to start a query, one to wait for the result.

​
vrin_query_async

Start a query against the Vrin knowledge base. Returns immediately with a job_id that the client must poll with vrin_check_job.

​
Input

ParameterTypeDefaultDescription
querystringrequiredThe natural-language question to answer.
modestring"context"Response shape. One of context, chat, expert, brainstorm, raw_facts. See response modes.
depthstring"basic"Retrieval depth. One of basic, thinking, research. Only applies when mode="context".
include_sourcesbooleantrueInclude source document references in the result.

​
Output

On success: 
{
  "success": true,
  "job_id": "b4f1a2c6-...-3e9d",
  "status": "working"
}
On failure (e.g. bad API key): 
{
  "success": false,
  "error": "Invalid or expired API key"
}

​
Behavior

  • The tool writes a job record to DynamoDB and invokes a worker Lambda asynchronously. It returns within ~200ms.
  • The job_id is a UUID. Keep it — you’ll need it for vrin_check_job.
  • Jobs expire one hour after creation.

​
vrin_check_job

Wait for a running query to complete. Long-polls internally for up to 55 seconds per call. Most queries complete inside the first call.

​
Input

ParameterTypeDescription
job_idstringThe UUID returned by vrin_query_async.

​
Output — status: "completed"

{
  "success": true,
  "job_id": "b4f1a2c6-...-3e9d",
  "status": "completed",
  "elapsed_seconds": 42,
  "result": {
    "summary": "ACME Corp reported $50M in Q4 2025...",
    "context": "Facts: ACME.revenue_q4 = $50M (source: earnings_report.pdf)...",
    "facts_count": 12,
    "sources": [
      {"title": "ACME Q4 Earnings", "chunk_id": "c_123", "score": 0.91}
    ],
    "entities": ["ACME Corp", "Jane Smith"]
  }
}
The exact fields in result depend on the mode passed to vrin_query_async. context mode returns structured facts for an agent to synthesize; chat mode returns a finished prose summary.

​
Output — status: "working"

{
  "success": true,
  "job_id": "b4f1a2c6-...-3e9d",
  "status": "working",
  "elapsed_seconds": 55,
  "progress": "Step 5/7: Scoring relevance",
  "message": "VRIN query is still processing (55s elapsed). Call vrin_check_job again — the query will complete soon."
}
When you see working, call vrin_check_job again with the same job_id. Most queries finish on the first or second call.

​
Output — status: "failed"

{
  "success": false,
  "job_id": "b4f1a2c6-...-3e9d",
  "status": "failed",
  "elapsed_seconds": 91,
  "error": "Upstream LLM timed out"
}
Do not retry the same job_id on failure — start a new query with vrin_query_async.

​
Output — status: "not_found"

{
  "success": false,
  "job_id": "b4f1a2c6-...-3e9d",
  "status": "not_found",
  "error": "Job not found. It may have expired (jobs expire after 1 hour)."
}

​
Canonical polling pattern

start = await session.call_tool(
    "vrin_query_async",
    {"query": "What is ACME's Q4 revenue?", "mode": "context"},
)
job_id = json.loads(start.content[0].text)["job_id"]

while True:
    resp = await session.call_tool("vrin_check_job", {"job_id": job_id})
    data = json.loads(resp.content[0].text)

    if data["status"] == "completed":
        return data["result"]
    if data["status"] == "failed":
        raise RuntimeError(data["error"])
    if data["status"] == "not_found":
        raise RuntimeError("Job expired — restart")
    # status == "working" → call again
There’s no time.sleep in that loop. vrin_check_job long-polls internally; calling it back-to-back is correct.

​
Resources

In addition to the two tools, the server exposes two MCP resources that clients can read without a tool call.

​
vrin://stats

Returns knowledge-base statistics for the authenticated user: 
{
  "entity_count": 1247,
  "fact_count": 8912,
  "document_count": 63
}

​
vrin://config

Returns server configuration: 
{
  "server_version": "1.0.0",
  "api_key_type": "standard",
  "infrastructure": "vrin-shared"
}
For vrin_ent_* keys, api_key_type is "enterprise" and infrastructure reflects the customer’s configured deployment.