Live context
Project progress, task counts, and service status change over time. Live Context lets an Agent query a data source through a fixed viking:// path and receive the result of that read's upstream call.
OpenViking binds a remote MCP tool and preset arguments to a searchable Markdown node. After finding the node, an Agent reads it in full, and OpenViking calls the tool. In this walkthrough, you will mount a pending-feedback query for the fictional Lighthouse project, change the count from 3 to 1, and read the same path to see the update.
How this differs from direct MCP calls
Both approaches can query current data. They differ in how the Agent finds and uses it:
| Agent calls MCP directly | Tool mounted through OpenViking | |
|---|---|---|
| Query workflow | Select a tool, supply arguments according to its definition, and call it | Retrieve a node described in business terms, then read it in full |
| In this example | Call project_status with project=Lighthouse | Find the “Lighthouse pending feedback” node and read its URI |
| Connection and maintenance | Configure the upstream MCP connection in the Agent host | Manage the upstream connection, tool binding, and preset arguments in OpenViking; the Agent uses OpenViking retrieval and reading |
Mounting gives these queries the same retrieval and reading workflow as ordinary resources, with fixed arguments reused through the node. Configuration happens when mounting; the Agent does not need to construct those arguments when using the node. Direct MCP calls are often simpler for a few tools whose arguments change frequently. Mounting fits frequent queries with stable arguments.
Prepare your environment
- OpenViking server and CLI: Complete the connection setup in Quickstart. Both must support live context; run
ov mcps --helpto check CLI support. Registration and mounting use the server's model and indexing configuration and may incur model costs. - Python and uv: The sample requires Python 3.10+ and uv. Check with
python3 --versionanduv --version.uv runinstalls the MCP dependency declared by the script. - Access permissions: Use the same OpenViking user throughout and ensure that it can create nodes under
viking://resources/onboarding-live-context-v1/.
Before starting, check the server and identity selected by the CLI and confirm that the MCP management API is available:
ov health
ov mcps listhealth should report a healthy server. With API key authentication, it should also identify the current Account, User, and role. mcps list should return a list; an empty list is fine. Use a User/Admin key with access to the target directory. In api_key mode, a Root key cannot perform this walkthrough's data operations. If either command reports a 404, a missing API key, or an unexpected identity, use ov config to check and select the correct connection.
This example assumes that the OpenViking server runs directly on your machine alongside the sample MCP server. With a containerized or remote OpenViking server, 127.0.0.1 refers to the server's own environment. Provide a Streamable HTTP MCP address reachable from that environment; see Live Context Integration and Arrangement.
Start the sample data source
Download the live context sample package and open a terminal in the download directory. Extract and start the sample. The included status.json starts with a fictional pending-feedback count of 3:
unzip live-context-demo-v1.zip
cd live-context-demo
uv run live-context-demo.pyKeep this terminal running. The script exposes a project_status tool at http://127.0.0.1:8765/mcp. Each call reads status.json from the script's directory again. The tool only queries data; it does not modify feedback.
If port 8765 is already in use, start with uv run live-context-demo.py --port 18765 and change the port to 18765 in the subsequent validate and add commands as well.
Open another terminal in the same directory. Verify that the OpenViking server can connect to the sample and discover its tool:
ov mcps validate '{"mcpServers":{"onboarding-live-v1":{"url":"http://127.0.0.1:8765/mcp"}}}'Continue when validation succeeds and reports one discovered tool. If the connection fails, check that the sample process is running and that OpenViking runs directly on the same machine.
Register and mount the node
Register the data source in the current user's tool directory and wait for tool processing:
ov mcps add '{"mcpServers":{"onboarding-live-v1":{"url":"http://127.0.0.1:8765/mcp"}}}' --wait
ov mcps show onboarding-live-v1Confirm that the tool list contains project_status with a string parameter named project. viking://~/tools/ refers to the current user's tool directory. If a repeat run reports that the Server already exists, use show to confirm that its address and tool still match this example before continuing.
Mount the tool in the demo directory with Lighthouse as the preset project:
ov mcps mount \
viking://~/tools/onboarding-live-v1/project_status.json \
viking://resources/onboarding-live-context-v1/status.md \
--title "Lighthouse pending feedback" \
--description "Query the current pending feedback count for the Lighthouse demo project." \
--args '{"project":"Lighthouse"}' \
--waitAfter mounting, inspect the binding:
ov mcps mounts --mcp onboarding-live-v1The result should include the status.md URI, the project_status tool, and the project=Lighthouse argument. Mounting the same URI again updates its binding; on repeat runs, confirm that it belongs to this demo.
Read and observe the change
First, retrieve the node using a business question, without specifying the upstream tool name:
ov find "How many pending feedback items does Lighthouse have now?" \
--uri viking://resources/onboarding-live-context-v1Find status.md in the results and check that its title and description refer to Lighthouse pending feedback. Retrieval locates the query entry point; read it in full to get the current count:
ov read viking://resources/onboarding-live-context-v1/status.mdThe result should contain these fields:
{"project":"Lighthouse","pending_feedback":3}In the second terminal, update the data source and read the same URI again:
printf '%s\n' '{"pending_feedback":1}' > status.json
ov read viking://resources/onboarding-live-context-v1/status.mdpending_feedback should now be 1. You changed only the sample data source, without reimporting a resource, syncing the tool catalog, or changing the mount. OpenViking called the same tool again when you read the node.
“Live” means that reading triggers a query. Data freshness depends on the upstream system. The source does not push changes through this mechanism, and answers an Agent has already produced do not update automatically.
Let an Agent use the node
If you have completed Agent onboarding, let the Agent retrieve and read the node itself. It must connect to the same server with an identity that can access both the node and the current user's tool directory. Use an Agent session without a direct connection to the sample MCP Server and enter:
How many pending feedback items does Lighthouse have now?
Search OpenViking under viking://resources/onboarding-live-context-v1/
for relevant context, read the matching node in full, and cite its URI in your answer.
If the read fails, explain the failure instead of reusing the previous count.Check the tool trace: the Agent should retrieve status.md, read it in full, and answer with 1 pending feedback item and the node URI. The prompt supplies only a business question and a search scope. It does not provide the upstream tool name, argument format, or full node path; OpenViking handles the binding.
The change from 3 to 1 demonstrates querying the data source at read time. Finding the node through retrieval and reading it through the common interface demonstrates how the Agent uses a mounted query.
Check the result
| Check | Expected result |
|---|---|
| Tool available | show includes project_status and its parameter definition |
| Correct binding | mounts shows the expected node URI, tool, and project argument |
| Node discoverable | Retrieval by business question includes status.md |
| First read | Lighthouse has 3 pending feedback items |
| Read after updating the source | The same URI returns 1 without remounting |
| Agent use (optional) | No direct sample MCP connection is needed; the trace includes retrieval and a full read, and the answer includes the latest count and source URI |
Common issues
| Symptom | What to check |
|---|---|
CLI does not recognize mcps, or the server lacks the endpoint | Update both to versions supporting live context; see CLI Setup |
| Validation or reading cannot connect | Keep the sample running and confirm that the MCP address is reachable from the OpenViking server |
| The count is still 3 | Update status.json in the sample script's directory, then read again |
| Retrieval does not find the node | Confirm the mount with mounts, then check mount processing, indexing, and the search scope; a successful direct read does not prove index readiness |
| Reading returns the node description | Use ov read without pagination; paginated reads and API reads with raw=true do not execute the upstream tool |
| Reading reports that the tool is not read-only | This sample declares a read-only tool. Tools explicitly marked as non-read-only or destructive require an explicit tool invocation |
| The Agent answers with the old count | Check for a new full read and verify the server and user identity |
find, search, and directory browsing do not call live nodes. An upstream tool error also causes the read to fail; check the data source first.
Continue using live context
Use this pattern for frequent queries such as project progress, ticket counts, or service status. Queries with stable arguments fit mounted live context; queries whose arguments depend on the question can use tool discovery and invocation. For Studio arrangement, authentication, tool-definition synchronization, and Context as Code, see Live Context Integration and Arrangement.
When finished, unmount this demo node before removing its Server registration:
ov mcps unmount viking://resources/onboarding-live-context-v1/status.md --wait
ov mcps remove onboarding-live-v1Return to the sample server's terminal and press Ctrl+C to stop it.