MCP server design

Preview server architecture for read-only video tools.

The MCP server should be an adapter over Ayneye REST and artifacts. It validates tenant scope, fetches durable resources, attaches evidence requirements, and blocks action authority by default.

Resources Server design Safety Quickstart Policies Agent tools World-State docs

Preview server architecture

Component	Responsibility	Failure mode to avoid
Auth adapter	Map session/API key to tenant and role	Cross-tenant artifact reads
Resource router	Expose stable ayneye:// artifact URIs	Ad hoc raw-video reads
Tool layer	get_scene_graph, get_timeline, get_evidence, ask_video, get_cost	Tools that imply physical control
Policy gate	Evaluate claim type, risk, confidence, review requirements	Silent high-risk conclusions
Audit log	Record request, tool, evidence_ref, answer, blocked action	Untraceable agent behavior

Minimal server sketch

# Preview-safe structure, not production activation
class AyneyeMCPServer:
    def list_resources(self, tenant_id, video_id):
        authorize_read_only(tenant_id, video_id)
        return [
            f"ayneye://videos/{{video_id}}/scene_graph",
            f"ayneye://videos/{{video_id}}/timeline",
            f"ayneye://videos/{{video_id}}/evidence",
            f"ayneye://videos/{{video_id}}/cost",
        ]

    def call_tool(self, name, args):
        if name not in {{"get_scene_graph", "get_evidence", "ask_video", "get_cost"}}:
            return {{"error": "tool_not_allowed", "review_required": True}}
        result = read_ayneye_artifact(name, args)
        return attach_policy_and_evidence_requirements(result)

Production-readiness checklist

Tenant-scoped authorization on every resource.
Immutable artifact version and evidence_ref in each answer.
Policy gate for identity, intent, access control, emergency, and employment outcomes.
Structured insufficient-evidence response instead of guesses.
Audit trail for every tool call and blocked action.
Clear UI language that MCP is preview unless separately activated.

The purpose of this page is to make the MCP boundary concrete for builders, buyers, and reviewers. A useful MCP integration is not a promise that an agent can watch everything and decide everything. It is a disciplined interface over already-materialized evidence. Each tool call should be tenant-scoped, read-only by default, evidence-aware, cost-aware, and auditable. If the request asks for identity, intent, physical access, emergency response, employment action, or destructive change, the tool returns a review-required state instead of pretending that a video artifact is a final decision. This keeps the product useful for developers while making it credible for security, legal, and operations teams.