Official Ampersand AI SDKs

Official Ampersand AI SDKs

This repo contains the official Ampersand AI SDK and the offical MCP server for Ampersand.

• AI SDK - Official Ampersand AI SDK that exposes tools for your AI agents to manage and interact with integrations with your customer's SaaS tools.
• MCP server - Official Ampersand MCP server that exposes the tools from the Ampersand AI SDK.

The examples directory contains examples of how to use the AI SDK with popular agent frameworks.

Ampersand is a platform for AI builders to add B2B SaaS integrations to their agentic apps. To learn more, visit our website.

Ampersand AI SDK

Installation

npm install @amp-labs/ai
# or
yarn add @amp-labs/ai
# or
pnpm add @amp-labs/ai

Usage

The SDK provides several modules that can be used depending on your framework preference:

Using with Vercel AI SDK

import { createRecord, updateRecord } from "@amp-labs/ai/aisdk";

// Use in your AI agent configuration
const tools = [createRecord, updateRecord];

Using with Mastra

import { createRecord, updateRecord } from "@amp-labs/ai/mastra";

// Use in your Mastra workflow
const tools = [createRecord, updateRecord];

Testing

The test directory contains end-to-end tests for the AI SDK.

Running the Simple Test

Prerequisites:

• OpenAI API key (required for AI model)
• Ampersand API credentials

1. Configure environment variables in test/.env:

   OPENAI_API_KEY=your_openai_api_key_here
   AMPERSAND_API_KEY=your_ampersand_api_key_here
   AMPERSAND_PROJECT_ID=your_project_id_here
   AMPERSAND_GROUP_REF=your_group_ref_here
   

2. Run the test:

   # From the root directory
   pnpm --filter ai-e2e-test test:simple
   
   # Or from the test directory
   cd test
   pnpm test:simple
   

The simple test demonstrates how to use the checkConnection tool with the Vercel AI SDK to verify Salesforce connections.

Testing Local Changes

The test uses your local SDK build via pnpm workspace linking. To test modifications to the SDK:

1. Make changes to SDK source files in sdk/lib/

2. Rebuild the SDK:

   pnpm --filter @amp-labs/ai build
   

3. Re-run the test to verify your changes:

   pnpm --filter ai-e2e-test test:simple
   

The test will use the freshly built SDK from sdk/dist/, allowing you to iterate quickly on SDK changes.

Ampersand MCP Server

Connect your agents to the 150+ connectors we offer at Ampersand via this multi-tenant MCP server. We expose the primitives we offer on the Ampersand platform as native tools here.

Connect to the remote MCP server

Add the following in your mcp.json in Cursor IDE or claude_desktop_config.json when using Claude desktop.

When running the server in SSE mode

If your MCP client supports headers:

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>",
      "headers": {
        "x-api-key": "<AMPERSAND_API_KEY>"
      }
    }
  }
}

If your MCP client does not support headers, you can pass the API key in the query param:

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?apiKey=<AMPERSAND_API_KEY>&project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>"
    }
  }
}

When running the server in stdio mode

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@amp-labs/mcp-server@latest",
        "--transport",
        "stdio",
        "--project",
        "<AMPERSAND_PROJECT_ID>",
        "--integrationName",
        "<AMPERSAND_INTEGRATION_NAME>",
        "--groupRef",
        "<AMPERSAND_GROUP_REF>"
      ],
      "env": {
        "AMPERSAND_API_KEY": "<AMPERSAND_API_KEY>"
      }
    }
  }
}

Connect to the local MCP server

Please refer to the mcp-server README for more information.

License

This project is licensed under the MIT license.

See LICENSE for more information.

Contributing

We welcome contributions! Please refer to the CONTRIBUTING.md file for more information.