# Basic Usage



<Callout type="info">
  **For AI agents:** Start with the Markdown entry point at [`/llms.txt`](/llms.txt). This page is also available at [`/docs/getting-started/basic-usage.mdx`](/docs/getting-started/basic-usage.mdx).
</Callout>

Server Configuration [#server-configuration]

First, create a server configuration file with your OAuth credentials:

```typescript
// lib/integrate.ts
import { createMCPServer, githubIntegration } from "integrate-sdk/server";

export const { client: serverClient } = createMCPServer({
  apiKey: process.env.INTEGRATE_API_KEY,
  integrations: [
    githubIntegration({
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
      scopes: ["repo", "user"],
    }),
  ],
});
```

You can get an API key from the [Integrate Dashboard](https://integrate.dev/dashboard/login).

Client Usage [#client-usage]

The client is automatically configured when making requests to the server.

Here's a complete example that calls a GitHub tool:

```typescript
import { client } from "integrate-sdk";

if (!(await client.isAuthorized("github"))) {
  await client.authorize("github");
}

const result = await client.github.createIssue({
  owner: "owner",
  repo: "repo",
  title: "Bug report",
  body: "Description of the bug",
});

console.log("Issue created:", result);
```

Client-Side vs Server-Side [#client-side-vs-server-side]

The SDK works in both browser and Node.js environments, but with different capabilities:

Browser Environment ✅ [#browser-environment-]

* Full OAuth authorization UI (popup/redirect)
* Make API calls to integrated services
* Complete session management

Server Environment 🖥️ [#server-environment-️]

* Make API calls with provider access tokens
* No OAuth UI (throws error if attempted)
* Perfect for backend API routes

```typescript
import { client } from "integrate-sdk";

client.setProviderToken("github", {
  accessToken: userAccessToken,
  tokenType: "Bearer",
  expiresIn: 3600,
});

const repos = await client.github.listRepos({ username: "octocat" });

await client.authorize("github");
```

💡 **Tip:** Handle OAuth authorization in the browser, then store the access token in your database for backend API calls.

Step-by-Step Breakdown [#step-by-step-breakdown]

1. Import the SDK [#1-import-the-sdk]

```typescript
import { client } from "integrate-sdk";
```

2. Set Up OAuth Credentials [#2-set-up-oauth-credentials]

Before using the SDK, you need to create OAuth apps for the services you want to integrate:

* **GitHub**: Create an OAuth App at [GitHub Developer Settings](https://github.com/settings/developers)
* **Gmail**: Create a project and OAuth 2.0 credentials in [Google Cloud Console](https://console.cloud.google.com)

Store your credentials in environment variables:

```bash
INTEGRATE_API_KEY=your_integrate_api_key
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GMAIL_CLIENT_ID=your_gmail_client_id
GMAIL_CLIENT_SECRET=your_gmail_client_secret
```

3. Call Tools [#3-call-tools]

```typescript
import { client } from "integrate-sdk";

const result = await client.github.createIssue({
  owner: "owner",
  repo: "repo",
  title: "Bug report",
  body: "Description of the bug",
});
```

List Available Tools [#list-available-tools]

To see what tools are available from the server:

```typescript
import { client } from "integrate-sdk";

const tools = await client.getEnabledToolsAsync();
console.log(
  "Available tools:",
  tools.map((t) => t.name)
);
```

`getEnabledTools()` returns only tools already cached locally. Use `getEnabledToolsAsync()` when you need fresh tool metadata from the server.

Error Handling [#error-handling]

Wrap your code in try-catch blocks to handle errors:

```typescript
import { client } from "integrate-sdk";

try {
  const result = await client.github.createIssue({
    owner: "owner",
    repo: "repo",
    title: "Bug report",
  });
  console.log("Success:", result);
} catch (error) {
  console.error("Error:", error.message);
}
```

Next Steps [#next-steps]

* Learn about [OAuth authorization](/docs/getting-started/basic-usage) to handle user authentication
* Explore [Built-in Integrations](/docs/integrations) to see what integrations are available
* Check out [Advanced Usage](/docs/getting-started/advanced-usage) for re-authentication, error handling, and more
* Integrate with [Vercel AI SDK](/docs/artificial-intelligence/vercel-ai-sdk) to give AI models access to your tools