Valstorm Hosted MCP Server (apps/valstorm-mcp-server)

Official hosted Model Context Protocol (MCP) server for the Valstorm Enterprise Platform.

This microservice acts as a stateless, high-performance SSE & JSON-RPC proxy to the Valstorm Core API (https://api.valstorm.com/v1), exposing granularly scoped tools for autonomous agents (Claude Desktop, Cursor, hermes profiles, internal enterprise workers) while offloading binary transfer via direct S3 recipes.

Architecture Highlights

• Dual Transport: Serves Streamable HTTP at /mcp (the current MCP standard, used by Claude and Cursor), the legacy SSE transport at /sse + /messages for older clients, and stdio for local CLI workflows.

• Stateless Transport: /mcp runs stateless, so any replica can answer any request. Multi-replica deployments need no session affinity.

• OAuth 2.1 Discovery: Publishes RFC 9728 protected-resource and RFC 8414 authorization-server metadata describing itself, delegating authorization and token endpoints to the core API.

• Stateless Proxy: Zero direct database attachments. Forwards JSON-RPC tool invocations to the core Valstorm REST API via httpx.AsyncClient.

• Granular Scopes: Strict token scope inspection (vfs:read, vfs:write, vfs:delete, record:read, record:write, record:delete, query:execute).

• Transfer Orchestrator: Bypasses JSON-RPC bloat by returning S3 presigned URLs and execution recipes for binary transfers.

• RAG & Search: Server-side Gemini RAG (vfs_ask) and OpenSearch hybrid retrieval (vfs_search).

• Zero N+1 Querying: Single-roundtrip document fetching (vfs_read_text via GET /vfs/file/{id}) and batch foreign key hydration (record_hydrate_batch via POST /object/hydrate-batch).

Related MCP server: Atlas MCP Server

Quickstart

Running locally with stdio:

uv run --project apps/valstorm-mcp-server valstorm-mcp --transport stdio

Running the hosted HTTP server (Streamable HTTP + SSE):

uv run --project apps/valstorm-mcp-server valstorm-mcp --transport streamable-http --host 0.0.0.0 --port 8660

Or via uvicorn directly:

uv run --project apps/valstorm-mcp-server uvicorn valstorm_mcp.server:app --host 0.0.0.0 --port 8660

Available Tool Registry (16 Tools)

Virtual File System (VFS)

1. vfs_search(query, limit=10, vault_id=None) — Hybrid OpenSearch vector & metadata chunk search.

2. vfs_ask(query, vault_id=None, limit=5) — Server-side Gemini RAG with synthesized markdown answer and citations.

3. vfs_read_text(file_id, max_bytes=100000) — High-performance single-roundtrip text reader (GET /vfs/file/{id}).

4. vfs_browse(target='root', browse_type='vault') — Explores VFS vaults, folder trees, or full hierarchy snapshots.

5. vfs_move(item_id, to_vault_id) — Atomic file or vault folder moves with path cascades.

6. vfs_prepare_upload(filename, vault_id=None, content_type="application/octet-stream") — Generates out-of-band upload recipe.

7. vfs_get_download_url(file_id) — Generates presigned S3 GET URL & terminal download recipe.

8. vfs_delete_file(file_id, confirm=False) — Secure file deletion guarded by confirmation flag.

Records, SQL, & Schemas

9. record_query_sql(query, bypass_cache=False, limit=50) — Executes custom Valstorm SQL engine (SELECT ... WHERE owner = ME).

10. record_query_mongo(collection, pipeline) — Structured document aggregation pipeline ($match, $group, $lookup, $facet).

11. record_hydrate_batch(ids) — Resolves foreign key ID arrays to display names and schemas in a single roundtrip.

12. record_get(api_name, record_id) — Fetches single record by ID.

13. record_create(api_name, record) — Creates single or batch records.

14. record_update(api_name, record_id, data) — Patches existing record fields.

15. record_delete(api_name, record_id, confirm=False) — Removes a record guarded by confirmation flag.

16. schema_inspect(api_name=None) — Introspects object schemas, fields, lookups, and validation rules.

License & Commercial Terms

Valstorm Hosted MCP Server is distributed under a Dual License model:

• Noncommercial Use (Community & Academic): Licensed under the PolyForm Noncommercial License 1.0.0. You are free to run, inspect, and evaluate the server for personal, hobby, or educational purposes without fees.

• Commercial & Enterprise Use: Any commercial use—including running internal business operations, powering SaaS backends, managed hosting, or client consulting deliverables—requires a commercial agreement.

For commercial licensing, enterprise BYOC terms, or official partner programs:

• Email: team@valstorm.com

• Website: Valstorm Pricing

• Enterprise Portal: Valstorm Enterprise

See CONTRIBUTING.md for community guidelines and development policies.

Copyright (c) 2026 Valstorm LLC. All rights reserved.