Previz/Developers/Connect a client

    curl, TypeScript and Python

    by the PREVIZ team

    Works today: one POST per call, JSON-RPC 2.0, your key in a header.

    Before you start

    Works todayCredential: API key as an Authorization header
    Server addresshttps://mcp.aimpreviz.comStreamable HTTP, JSON-RPC 2.0. Your key goes in the Authorization header as a bearer token.

    You need a PREVIZ account and an API key. Mint the key in Account → API keys and give it a monthly credit cap: an agent holding the key can spend inside that cap and no further, and a paid tool answers with a quote and runs nothing until it is called again with that quote's token. The key is shown once; keep it in an environment variable named PVZ_KEY, which the snippets below read.

    A key holds only the access classes its owner gave it, set in Account → API keys → the key's Access: a new key holds read and write, and spend needs a monthly credit cap. tools/list shows only the tools a key holds, and a call to any other is refused with INSUFFICIENT_SCOPE. A key made before access classes existed keeps what it could do then (read, write, spend and live) until its owner sets its access; produce is given, never inherited.

    Set it up

    1. 01

      curl

      The door is stateless enough to call a tool directly: no session is needed for tools/call. One message per POST; batches are refused.

      Terminal
      curl -s https://mcp.aimpreviz.com \
        -H "Authorization: Bearer $PVZ_KEY" \
        -H "Content-Type: application/json" \
        -H "Accept: application/json, text/event-stream" \
        -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    2. 02

      TypeScript

      With the Model Context Protocol project's package (npm install @modelcontextprotocol/sdk).

      TypeScript
      import { Client } from "@modelcontextprotocol/sdk/client/index.js";
      import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
      
      const transport = new StreamableHTTPClientTransport(new URL("https://mcp.aimpreviz.com"), {
        requestInit: { headers: { Authorization: `Bearer ${process.env.PVZ_KEY}` } },
      });
      const client = new Client({ name: "my-pipeline", version: "1.0.0" });
      await client.connect(transport);
      const projects = await client.callTool({ name: "list_projects", arguments: {} });
    3. 03

      Python

      With the Model Context Protocol project's package (pip install mcp).

      Python
      import asyncio, os
      from mcp import ClientSession
      from mcp.client.streamable_http import streamablehttp_client
      
      async def main():
          headers = {"Authorization": f"Bearer {os.environ['PVZ_KEY']}"}
          async with streamablehttp_client("https://mcp.aimpreviz.com", headers=headers) as (read, write, _):
              async with ClientSession(read, write) as session:
                  await session.initialize()
                  projects = await session.call_tool("list_projects", {})
      
      asyncio.run(main())

    Config formats belong to each client and change with its releases; if a field name above is refused, check the client's own documentation for its current remote-server entry. The address and the header never change.

    Test the connection

    Two free calls prove the whole path: the key, the address, the client and your projects. Neither spends a credit.

    1. Ask for your PREVIZ projects. The client calls list_projects and answers with their names and ids. An empty list means the key reaches no project yet, not that the connection failed.
    2. Ask what a cinematic frame of something would cost in one of them. The client calls plan_quote or generate_frame without a quote token, and answers with a price. Nothing renders and nothing is charged.
    3. If the client reports 401 or unauthorized, the key is missing, mistyped or revoked; if it reports no tools, the address or the transport is wrong. Fix that before anything else.

    What to know

    • A PREVIZ client package of its own is not built yet; the packages above are the protocol's, and any MCP client works.
    • A REST mapping of the same operations is not built yet; every call is JSON-RPC to the address above.
    • Spend with the quote's quoteToken or your own idempotencyKey, never a bare confirm: then a call the framework retries after a timeout joins the first run and is charged once (see Quotes and money).
    • From a browser, the door refuses most web origins, and an origin it accepts does not protect a key placed in a page; call it from a server and keep the key there.