MCP server

Vision runs a Model Context Protocol server so AI assistants such as Claude can read a workspace's Apps with the same scoped, revocable credentials as any other integration.

What the server offers

• Transport: MCP Streamable HTTP, stateless, POST only, JSON responses. Protocol version 2025-11-25.
• Endpoint: https://<environment host>/mcp (see Environments).
• Auth: a Vision Platform access token as Authorization: Bearer .... Without one the server answers 401 with {"error":{"code":"invalid_token",...}}.
• Scoped tool list: tools/list returns only the tools your token's scopes allow, so an assistant never sees a tool it cannot call.

Tools

Each tool's input schema mirrors the App operation it reads (page size, cursor, filters). Calls are brokered by Vision Core to the owning App, which applies its own workspace and record rules. Run tools/list for the exact schemas your token can use.

Authentication

Vision tokens last at most five minutes and the server does not yet offer an interactive OAuth sign-in, so an assistant needs something that keeps a fresh token. Use the Vision MCP bridge: a small, dependency-free Node.js script that runs on your machine, holds your client credentials, exchanges and refreshes tokens, and relays MCP messages over stdio.

1. Create an API client for the assistant (one client per assistant, identity class agent) with only the read scopes it needs.
2. Download the bridge: vision-mcp-bridge.mjs. Node.js 20 or later.
3. Point your MCP client at it, as below.

The bridge reads VISION_CLIENT_ID, VISION_CLIENT_SECRET, VISION_BASE_URL (default https://preview.runonvision.com) and optionally VISION_SCOPES. It never writes the secret to the MCP channel or its log.

Connect Claude Code

claude mcp add vision \
  --env VISION_CLIENT_ID=vcr_your_client_id \
  --env VISION_CLIENT_SECRET="$(cat ~/.config/vision/client-secret)" \
  -- node /absolute/path/to/vision-mcp-bridge.mjs

Then ask Claude, for example, "Which invoices are overdue in Vision?" Use claude mcp list to check the connection.

Connect Claude Desktop and other clients

Add the bridge to the client's MCP configuration. For Claude Desktop that is claude_desktop_config.json:

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["/absolute/path/to/vision-mcp-bridge.mjs"],
      "env": {
        "VISION_CLIENT_ID": "vcr_your_client_id",
        "VISION_CLIENT_SECRET": "your_client_secret",
        "VISION_BASE_URL": "https://preview.runonvision.com"
      }
    }
  }
}

Cursor, Windsurf, VS Code and other stdio MCP clients use the same command, args and env. The configuration file then holds a secret: keep it readable only by you, and revoke the client from Vision if the machine is lost.

Call it directly

For a quick check without a bridge, mint a token and post JSON-RPC yourself:

TOKEN=$(curl -s https://preview.runonvision.com/oauth/token \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode "client_id=$VISION_CLIENT_ID" \
  --data-urlencode "client_secret=$VISION_CLIENT_SECRET" | jq -r .access_token)

curl https://preview.runonvision.com/mcp \
  --header "authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --header 'accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A remote-connector setup with a static header (for example claude mcp add --transport http ... --header "Authorization: Bearer ...") works only until the token expires, five minutes later.

Safety

• All tools are read-only and annotated readOnlyHint: true.
• An assistant sees only the workspace its client belongs to, and only the tools its scopes allow.
• Give each assistant its own client so you can revoke one without breaking others; every call is attributed to that client.
• Tool results can include customer data. Treat the assistant's conversation history with the same care as an export.

Roadmap

Planned, not yet available: production enablement; OAuth authorization server metadata and interactive sign-in so remote connectors (such as Claude's custom connectors) can connect without a bridge; write tools with explicit confirmation; Directory and Calendar tools.