Previz/Developers/Connect a client

    Claude API (Messages API connector)

    by the PREVIZ team

    Works today: the connector sends your PREVIZ key as a bearer token.

    Before you start

    Works todayCredential: API key as the connector's authorization_token
    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

      Declare the server and its toolset

      Two parameters go together: mcp_servers names the connection, and an mcp_toolset entry in tools exposes it to the model. The connector is a beta of the Messages API, so the request carries its beta header. Replace YOUR_MODEL with the id of a model your own account can use; the request is refused until you do.

      curl
      curl https://api.anthropic.com/v1/messages \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2023-06-01" \
        -H "anthropic-beta: mcp-client-2025-11-20" \
        -H "content-type: application/json" \
        -d '{
          "model": "YOUR_MODEL",
          "max_tokens": 4096,
          "mcp_servers": [{
            "type": "url", "name": "previz",
            "url": "https://mcp.aimpreviz.com",
            "authorization_token": "'"$PVZ_KEY"'"
          }],
          "tools": [{ "type": "mcp_toolset", "mcp_server_name": "previz" }],
          "messages": [{ "role": "user", "content": "List my PREVIZ projects." }]
        }'
    2. 02

      The same request in Python

      With the official package for the Claude API. Replace YOUR_MODEL with the id of a model your own account can use; the request is refused until you do.

      Python
      import os, anthropic
      
      client = anthropic.Anthropic()
      reply = client.beta.messages.create(
          model="YOUR_MODEL",
          max_tokens=4096,
          betas=["mcp-client-2025-11-20"],
          mcp_servers=[{
              "type": "url",
              "name": "previz",
              "url": "https://mcp.aimpreviz.com",
              "authorization_token": os.environ["PVZ_KEY"],
          }],
          tools=[{"type": "mcp_toolset", "mcp_server_name": "previz"}],
          messages=[{"role": "user", "content": "List my PREVIZ projects."}],
      )

    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

    • The connector calls PREVIZ from Claude's servers, so every call is made with the key you pass; give it a key with a monthly cap.
    • To expose only some tools, set the toolset's default_config to disabled and enable the ones you want in configs.