SDK Overview

Connect SaaS integrations with managed per-user auth and hand their tools to any LLM — OpenAI, Anthropic, or the Vercel AI SDK.

@protoboxai/sdk lets you give an AI agent the ability to take real actions in SaaS apps — GitHub, Gmail, and the rest of the catalog — with the OAuth handled for you, per end-user. You connect an app once for each of your users, then hand that app's tools to any LLM in one line. Tool execution runs on the Protobox platform using the stored credential, so tokens never touch your process.

This is the current SDK — @protoboxai/sdk at version 2.x. The 1.x line on the same package name is an older, different API; see Migrating if you are coming from it.

Building a SaaS product on Protobox? The use-case recipes walk every embedding scenario end-to-end — user connects, agent tool-calling, MCP sessions, published servers, approvals, automations.

Why the SDK

Every integration is already reachable over MCP at https://<workspace>.protobox.app/mcp. The SDK exists for the things a raw MCP URL can't do ergonomically from your own backend:

Managed per-user auth — programmatically start a hosted OAuth flow for one of your users and let Protobox store + refresh their credential.
One-line LLM handoff — convert an integration's tools into OpenAI, Anthropic, or Vercel AI SDK format and run the model's tool-calls back through the platform.

Core concepts

Concept	What it is
Integration	A connectable app in the catalog (`github`, `gmail`, …) and the actions it exposes.
Entity	One of your end-users. Identified by a `userId`; connections and tool calls are isolated per entity.
Connection	A connected account with a managed, auto-refreshed credential (per-user or workspace-level).
Adapter	A one-line bridge that hands tools to OpenAI / Anthropic / the Vercel AI SDK and runs their tool-calls.

The shape of a program

import { ProtoboxSDK } from '@protoboxai/sdk';

const protobox = new ProtoboxSDK({ apiKey: process.env.PROTOBOX_API_KEY! });

// 1. Scope to one of your end-users
const user = protobox.entity('user_123');

// 2. Connect their GitHub via managed OAuth — redirect them to `authorizeUrl`
const { authorizeUrl } = await user.connect('github');
// ... user completes the hosted OAuth flow in the browser ...
await user.waitUntilActive('github');

// 3. Hand GitHub's tools to Claude
const gh = user.forLLM('anthropic', { integrationId: 'github' });
const tools = await gh.tools();
const message = await anthropic.messages.create({ model, messages, tools });
const results = await gh.run(message.content); // executed server-side, per-user creds

Where to go next

Quickstart

Managed auth & connections

Framework adapters

Error handling

Not yet in the SDK

Triggers / webhooks — the protobox.triggers namespace is reserved; calls throw NotImplementedError until event delivery ships.
Python — a Python SDK mirroring this surface is planned; TypeScript is current.
Workspace management — the workspace module from the legacy SDK has no v2 equivalent yet. Knowledge (protobox.knowledge) and prompts (protobox.prompts) landed in 2.2.0.

Migrating from 1.x

@protoboxai/sdk 1.x is deprecated. 2.x leads with agent tooling (integrations, per-user connections, framework adapters) instead of raw platform CRUD. The client is still ProtoboxSDK, but the modules and the auth model differ — start from the Quickstart rather than porting call-for-call.

Search