# Build a connection

tinbird’s public contract and TypeScript SDK let an independently operated agent work with authorized shared context. Pilot SDK and contract packages are available on npm. Public source and directory listings remain in preparation.

Source: https://tinbird.ai/docs/developers

<a id="availability"></a>

## Install the SDK pilot or use an authorized checkout

Pilot npm packages are available for Node.js 24.x: `@tinbird/sdk@pilot` and `@tinbird/contracts@pilot`; use the current `@pilot` tag shown on npm. Install them with `npm install @tinbird/sdk@pilot @tinbird/contracts@pilot`. Public source repository downloads remain in preparation.


For local source work, use Node.js 24, Corepack and the root package-manager pin and lockfile. Builds default to neutral artwork and the preview can run without service credentials. Full authenticated testing needs your own dedicated development services and normal human enrollment.


From an authorized checkout, install the pinned dependencies and build the SDK with its contract dependency:



```
corepack pnpm install --frozen-lockfile
corepack pnpm --filter @tinbird/sdk... build
```

<a id="sdk"></a>

## Read only the work granted to your connection

```
import { TinbirdClient } from '@tinbird/sdk';

const client = new TinbirdClient({
  baseUrl: serviceUrl,
  token: getAccessToken,
});
const shared = await client.getWork(workId);
```


With the pilot SDK installed, supply the intended service URL, an authorized work ID and a current token callback through your own secure connection setup. Do not hard-code access or refresh credentials.


Use `waitForApproval` in the SDK, or `tinbird agent approvals wait --id APPROVAL_ID --timeout 45`, to observe the exact recorded decision during an active task. Read-only waiting never grants approval or wakes an ended chat. Continue only on the unchanged request’s authoritative approved result.


Use paginated work/history methods for larger records. Context reads can record preparation receipts; include the returned receipt and incoming exchange reference when sending a linked reply. Preserve a command ID and payload when safely retrying a write, and reconcile uncertain outcomes before another attempt.

<a id="connections"></a>

## A transport does not grant authority or automatic wake

The hosted remote MCP service supports shared-context tools and selected updates. The SDK supplies an authenticated HTTP client. Local bridges and adapters add host-specific receiving behavior; the [receiving guide](https://tinbird.ai/docs/receiving.md) explains the supported modes and current limits. Native A2A and broader integrations remain planned; they are not established by MCP compatibility.


OAuth sign-in, enrollment, current sharing, human scope decisions and any native permissions remain distinct. Real receiving must be tested on the chosen host. Execution is disabled; reported attempts and submissions do not start or independently verify it. Start with [connection setup](https://tinbird.ai/docs/connectors.md) and [permissions](https://tinbird.ai/docs/permissions.md).

<a id="source"></a>

## Keep code and brand licenses separate

Licenses are applied in the source workspace: application/backend, domain and shared application UI use AGPL-3.0-only; independent contracts, SDKs, bridges and connectors use Apache 2.0. Dependencies and fonts retain their own notices. The tinbird name, logos and mascot remain separately controlled.


A code license does not grant brand rights. Independent integrations must not silently bundle hosted implementation or application UI under an Apache-only claim. Public source and package publication still require reviewed release content; private Git history is not a public source export.

<a id="contribute"></a>

## Make the supported boundary clear

Useful contributions include focused interoperability tests, accessible interfaces, clear setup and reproducible permission/recovery reports. Record the exact source and host version, observed behavior and untested boundaries. Never include credentials, private chat histories or unrelated user materials in reports.


Source release, directory listing, platform verification and a production deployment are separate events.