---
title: "Install"
description: "Installation guide for the Server AI Toolkit. Learn how to install, configure authentication, and start using the Server AI Toolkit cloud service."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/install"
---

# Install

Installation guide for the Server AI Toolkit. Learn how to install, configure authentication, and start using the Server AI Toolkit cloud service.

- **1. Request access**

  Request access to the Server AI Toolkit by
  contacting our team.
- **2. Install the package**

  The Server AI Toolkit package is open source. Install it from the public npm registry using npm
  or your preferred package manager.
- **3. Authenticate to the service**

  Configure your Content AI credentials to access the Server AI Toolkit service.

First, contact our team to get access to the Server AI Toolkit.

Then, install the open-source Server AI Toolkit package:

```bash
npm install @tiptap/server-ai-toolkit
```

## Get editor context

First, install the `ServerAiToolkit` extension in your editor. This will modify your editor schema so that your documents are compatible with the Server AI Toolkit.

To use the Server AI Toolkit API, get the editor context from your Tiptap editor. This JSON object contains the editor schema and other data that the AI server needs to understand valid document content.

```tsx
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getEditorContext, ServerAiToolkit } from '@tiptap/server-ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit, ServerAiToolkit],
})

// Get editor context from the editor
const editorContext = getEditorContext(editor)
```

Pass `editorContext` on every request you make to the Server AI Toolkit.

> **Store the editor context:**
>
> The editor context returned by `getEditorContext` is JSON-serializable. You can store it in your
> database and update it only when your editor extensions or schema change.

> **Using custom nodes?:**
>
> If your editor includes custom nodes or marks, configure them with `addJsonSchemaAwareness`. See
> the [custom nodes guide](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/advanced-guides/custom-nodes.md).

For more details, see the [Editor context API reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/editor-context.md).

## Set up authorization

The Server AI Toolkit is a cloud or on-premises service. Authenticate to access its REST API.

1. **Get your App ID and secret key** on the [Tiptap Cloud AI settings](https://cloud.tiptap.dev/v2/cloud/ai) page.
2. **Get your Document Server credentials** (ID and management API secret) on the [Document Server settings](https://cloud.tiptap.dev/v2/configuration/document-server) page. These are included as JWT claims so the Server AI Toolkit can automatically fetch and save your Tiptap Cloud documents.
3. **Generate a JWT** using a library like `jsonwebtoken`. In production, always create JWTs **server-side** to keep your secret safe.
4. **Use the JWT** in your API requests. Pass it in the `Authorization` header as a Bearer token and the App ID in `X-App-Id`.

### Environment variables

Configure the following environment variables:

```sh
# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_CLOUD_AI_SECRET=your-secret-key
TIPTAP_CLOUD_AI_APP_ID=your-app-id
TIPTAP_CLOUD_DOCUMENT_SERVER_ID=your-tiptap-cloud-document-server-id
TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET=your-tiptap-cloud-document-management-api-secret
```

- **TIPTAP\_CLOUD\_AI\_API\_URL**: The base URL for the Server AI Toolkit API.
- **TIPTAP\_CLOUD\_AI\_SECRET**: Your "Content AI Secret" from the [Content AI settings](https://cloud.tiptap.dev/v2/cloud/ai) page. Used to sign the JWT.
- **TIPTAP\_CLOUD\_AI\_APP\_ID**: Your "Content AI App ID" from the [Content AI settings](https://cloud.tiptap.dev/v2/cloud/ai) page.
- **TIPTAP\_CLOUD\_DOCUMENT\_SERVER\_ID**: Your Tiptap Cloud Document Server ID from the [Document Server settings](https://cloud.tiptap.dev/v2/configuration/document-server) page. Included as the `experimental_document_server_id` JWT claim so the Server AI Toolkit can fetch and save documents automatically.
- **TIPTAP\_CLOUD\_DOCUMENT\_SERVER\_MANAGEMENT\_API\_SECRET**: Your Document Server management API secret. Included as the `experimental_document_server_management_api_secret` JWT claim for document access.

### Create a JWT token

This function generates a JWT from `TIPTAP_CLOUD_AI_SECRET` for authenticating with the Server AI Toolkit API. It includes Document Server credentials so the Server AI Toolkit can automatically fetch and save your Tiptap Cloud documents.

```ts
// lib/server-ai-toolkit/create-jwt-token.ts
import jwt from 'jsonwebtoken'

/**
 * Generates a JWT from TIPTAP_CLOUD_AI_SECRET for authenticating with the Server AI Toolkit API
 */
export function createJwtToken(): string {
  return jwt.sign(
    {
      // Document Server credentials for automatic document fetching/saving
      experimental_document_server_id: process.env.TIPTAP_CLOUD_DOCUMENT_SERVER_ID,
      experimental_document_server_management_api_secret:
        process.env.TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET,
    },
    process.env.TIPTAP_CLOUD_AI_SECRET,
    { expiresIn: '1h' },
  )
}
```

### Get authentication headers

This function returns the authentication headers required for all Server AI Toolkit API requests.

```ts
// lib/server-ai-toolkit/get-auth-headers.ts
import { createJwtToken } from './create-jwt-token'

/**
 * Returns the authentication headers for the Server AI Toolkit API
 */
export function getAuthHeaders(): Record<string, string> {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${createJwtToken()}`,
    'X-App-Id': process.env.TIPTAP_CLOUD_AI_APP_ID,
  }
}
```

> **Alternative: provide documents directly:**
>
> If you manage documents in your own storage instead of Tiptap Cloud, you can omit the
> `experimental_document_server_id` and `experimental_document_server_management_api_secret` JWT
> claims and pass documents directly via the `document` field in API requests. See the [REST API
> reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api.md).

## Call API endpoints

Once authenticated, call the Server AI Toolkit API endpoints using the `getAuthHeaders` function:

```ts
import { getAuthHeaders } from './lib/server-ai-toolkit/get-auth-headers'

const apiBaseUrl = process.env.TIPTAP_CLOUD_AI_API_URL || 'https://api.tiptap.dev'

const response = await fetch(`${apiBaseUrl}/v3/ai/toolkit/tools`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
  }),
})

const tools = await response.json()
```

For complete API documentation, see the [REST API reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api.md).

## Next steps

Now that you've set up the Server AI Toolkit, start building your AI integration:

[AI agent chatbot
More →Build a conversational AI capable of editing documents and interacting through chat.](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/agents/ai-agent-chatbot.md)