MCP Tool Reference

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

Parameter	Type	Default	Description
`query`	`string`	required	The natural-language question to answer.
`mode`	`string`	`"context"`	Response shape. One of `context`, `chat`, `expert`, `brainstorm`, `raw_facts`. See response modes.
`depth`	`string`	`"basic"`	Retrieval depth. One of `basic`, `thinking`, `research`. Only applies when `mode="context"`.
`include_sources`	`boolean`	`true`	Include 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

Parameter	Type	Description
`job_id`	`string`	The 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.

Get Started

MCP Server

CLI

Python SDK

TypeScript SDK

Concepts

Guides

MCP Tool Reference

`vrin_query_async`

Input

Output

Behavior

`vrin_check_job`

Input

Output — `status: "completed"`

Output — `status: "working"`

Output — `status: "failed"`

Output — `status: "not_found"`

Canonical polling pattern

Resources

`vrin://stats`

`vrin://config`

​vrin_query_async

​Input

​Output

​Behavior

​vrin_check_job

​Input

​Output — status: "completed"

​Output — status: "working"

​Output — status: "failed"

​Output — status: "not_found"

​Canonical polling pattern

​Resources

​vrin://stats

​vrin://config

`vrin_query_async`

Input

Output

Behavior

`vrin_check_job`

Input

Output — `status: "completed"`

Output — `status: "working"`

Output — `status: "failed"`

Output — `status: "not_found"`

Canonical polling pattern

Resources

`vrin://stats`

`vrin://config`